Opentrons MCP

🚀 Opentrons MCP Server

A Model Context Protocol (MCP) server for Opentrons robot automation and API documentation. This tool offers both comprehensive API documentation and direct robot control capabilities for Opentrons Flex and OT - 2 robots.

✨ Features

API Documentation Tools

• Search Endpoints: Locate API endpoints by functionality, method, or keyword.
• Endpoint Details: Obtain comprehensive information about specific API endpoints.
• Category Browsing: List endpoints according to functional categories.
• API Overview: Get a high - level overview of the entire Opentrons HTTP API.

Robot Automation Tools

• Protocol Management: Upload, list, and manage protocol files.
• Run Control: Create runs, start/stop execution, and monitor progress.
• Robot Health: Check connectivity and system status.
• Hardware Control: Home the robot, control lights, and perform basic operations.

📦 Installation

From npm (recommended)

npm install -g opentrons-mcp

From source

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

🛠️ Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

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

If installed from source:

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

💻 Available Tools

Documentation Tools

search_endpoints

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

• query (required): Search term
• method (optional): Filter by HTTP method (GET, POST, PUT, DELETE, PATCH)
• tag (optional): Filter by API category
• include_deprecated (optional): Include deprecated endpoints

get_endpoint_details

Get comprehensive details about a specific API endpoint.

• method (required): HTTP method
• path (required): API endpoint path

list_by_category

List all endpoints in a specific functional category.

• category (required): API category (Health, Control, Protocol Management, etc.)

get_api_overview

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

Automation Tools

upload_protocol

Upload a protocol file to an Opentrons robot.

• robot_ip (required): Robot IP address
• file_path (required): Path to protocol file (.py or .json)
• protocol_kind (optional): "standard" or "quick - transfer" (default: "standard")
• key (optional): Client tracking key
• run_time_parameters (optional): Runtime parameter values

get_protocols

List all protocols stored on the robot.

• robot_ip (required): Robot IP address
• protocol_kind (optional): Filter by protocol type

create_run

Create a new protocol run on the robot.

• robot_ip (required): Robot IP address
• protocol_id (required): ID of protocol to run
• run_time_parameters (optional): Runtime parameter values

control_run

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

• robot_ip (required): Robot IP address
• run_id (required): Run ID to control
• action (required): "play", "pause", "stop", or "resume - from - recovery"

get_runs

List all runs on the robot.

• robot_ip (required): Robot IP address

get_run_status

Get detailed status of a specific run.

• robot_ip (required): Robot IP address
• run_id (required): Run ID to check

robot_health

Check robot health and connectivity.

• robot_ip (required): Robot IP address

control_lights

Turn robot lights on or off.

• robot_ip (required): Robot IP address
• on (required): true to turn lights on, false to turn off

home_robot

Home robot axes or specific pipette.

• robot_ip (required): Robot IP address
• target (optional): "robot" for all axes, "pipette" for specific mount
• mount (optional): "left" or "right" (required if target is "pipette")

💻 Usage Examples

With Claude Desktop

Screenshot showing the Opentrons MCP server in action with Claude Desktop after asking for current protocols with opentrons for the Flex, give it the robot ip!

Once configured, you can use natural language to control your robot:

Upload a protocol:

Upload the protocol file at /path/to/my_protocol.py to my robot at 192.168.1.100

Check robot status:

Check if my robot at 192.168.1.100 is healthy and ready

Run a protocol:

List all protocols on my robot, then create and start a run for the latest one

Monitor progress:

Show me the status of run abc123 on my robot

Programmatic Usage

import { Client } from "@modelcontextprotocol/sdk/client/index.js";

// Connect to MCP server
const client = new Client(/* transport */);

// Upload protocol
await client.request({
  method: "tools/call",
  params: {
    name: "upload_protocol",
    arguments: {
      robot_ip: "192.168.1.100",
      file_path: "/path/to/protocol.py",
      protocol_kind: "standard"
    }
  }
});

📋 Requirements

• Node.js 18+
• Opentrons robot with HTTP API enabled (port 31950)
• Network connectivity between client and robot

🤖 Robot Setup

Ensure your Opentrons robot is:

1. Connected to the same network as your client.
2. Running robot software version 7.0.0+.
3. Accessible on port 31950 (default for HTTP API).

You can verify connectivity by visiting http://your-robot-ip:31950/health in a browser.

📚 API Reference

This tool provides access to the complete Opentrons HTTP API, including:

• Protocol Management: Upload, analyze, and manage protocol files.
• Run Management: Create, control, and monitor protocol runs.
• Hardware Control: Robot movement, homing, lighting, and calibration.
• System Management: Health monitoring, settings, and diagnostics.
• Module Control: Temperature modules, magnetic modules, thermocyclers.
• Data Management: CSV files for runtime parameters.

For detailed API documentation, use the search and documentation tools provided by this MCP server.

🔧 Troubleshooting

Cannot connect to robot

• Verify that the robot IP address is correct.
• Ensure the robot is powered on and connected to the network.
• Check that port 31950 is accessible.
• Confirm that the robot software is running.

Protocol upload fails

• Verify that the file path exists and is readable.
• Ensure the protocol file is in valid Python (.py) or JSON format.
• Check the available disk space on the robot.
• Confirm that the protocol is compatible with the robot type (OT - 2 vs Flex).

Run execution issues

• Verify that all required labware and modules are attached.
• Check the robot calibration status.
• Ensure the protocol analysis completed successfully.
• Confirm that there are no hardware errors or conflicts.

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

📄 License

No license go brazy

🔗 Related Projects

• Opentrons API Documentation
• Model Context Protocol
• Claude Desktop