Opentrons

You run an MCP server to access Opentrons API documentation and to automate robot control. It lets you discover API endpoints, manage protocols, run protocols, and perform hardware actions on Opentrons Flex and OT-2 robots from a single, programmable interface.

How to use

Connect to the MCP server from your MCP client to browse the API, upload protocols, create and manage runs, and directly control the robot. Use the documented tools to search endpoints, get endpoint details, and list endpoints by category. For automation, upload your protocol files, start runs, monitor progress, check robot health, and issue hardware commands such as homing axes or toggling lights.

How to install

Prerequisites you need before installing: Node.js 18+ and network access to your Opentrons robot (HTTP API on port 31950). Then, perform one of the following installation paths.

npm install -g opentrons-mcp

Or install from source and run the MCP server locally. Clone the repository, install dependencies, and prepare to run the server.

git clone https://github.com/yerbymatey/opentrons-mcp.git
cd opentrons-mcp
npm install

Configuration

Configure the MCP server to be used by your Claude Desktop client. If you are using the prebuilt binary, you wire up the CLI tool as a standard MCP server within Claude.

{
  "mcpServers": {
    "opentrons": {
      "command": "opentrons-mcp",
      "args": []
    }
  }
}

If you installed from source, run the server with Node and point to the index file.

{
  "mcpServers": {
    "opentrons": {
      "command": "node",
      "args": ["/path/to/opentrons-mcp/index.js"]
    }
  }
}

Requirements

Ensure you have Node.js 18+ installed, an Opentrons robot with HTTP API enabled on port 31950, and network connectivity between your client and the robot.

Robot Setup

Make sure your Opentrons robot is on the same network as your client, running software version 7.0.0+ and accessible via port 31950. Verify connectivity by visiting http://your-robot-ip:31950/health from a browser.

Troubleshooting

Cannot connect to robot: confirm the IP, ensure the robot is powered on, verify port 31950 is reachable, and that the HTTP API is enabled.

Protocol upload fails: check the file path, ensure the protocol is valid (.py or .json), verify disk space, and confirm compatibility with the robot model.

Run execution issues: verify labware and modules are attached, check calibration, confirm analysis completed, and ensure no hardware conflicts.

API overview and usage notes

The MCP server provides access to the Opentrons HTTP API for protocol management, run management, hardware control, and system diagnostics. Use the documented tools to perform searches, get endpoint details, and manage protocol runs and robot health.

Notes on tools and usage patterns

You can upload a protocol, list available protocols, create and start a run, monitor run status, and control hardware such as homing the robot or turning lights on and off. Use natural language or programmatic calls to achieve these tasks.

API/Automation Examples and hosting

You can use a client SDK to connect to the MCP server and perform actions such as uploading protocols and querying runs. The client sends requests to the server to trigger robot actions and retrieve status information.

Available tools

search_endpoints

Search Opentrons HTTP API endpoints by functionality, method, path, or keyword.

get_endpoint_details

Get comprehensive details about a specific API endpoint.

list_by_category

List all endpoints in a specific functional category.

get_api_overview

Get high-level overview of the Opentrons HTTP API structure and capabilities.

upload_protocol

Upload a protocol file to an Opentrons robot.

get_protocols

List all protocols stored on the robot.

create_run

Create a new protocol run on the robot.

control_run

Control run execution (play, pause, stop, resume).

get_runs

List all runs on the robot.

get_run_status

Get detailed status of a specific run.

robot_health

Check robot health and connectivity.

control_lights

Turn robot lights on or off.

home_robot

Home robot axes or specific pipette.