Opentrons OT-2 / Flex

Opentrons OT-2 / Flex — MCP Server

Let an AI agent upload and check protocols, review the deck layout with you, start, pause, stop and resume runs, follow their progress, and read pipettes and modules on Opentrons Flex and OT-2 liquid-handling robots through the robot's documented HTTP API.

Why this server rather than a generic HTTP wrapper: it refuses to start a run unless the robot's own protocol analysis passed, the user has confirmed the deck, the door is closed, the E-stop is released and module setpoints are within your limits. It exposes no single-move pipetting commands, keeps pause and stop available even in read-only mode, and records every HTTP request in the command log.

Try it without hardware

uvx labmcp-opentrons --simulate --checkuvx labmcp-opentrons --simulate --option sim_model=ot2 --check   # simulate an OT-2

The simulator runs protocols in memory: Python protocols are compiled and scanned for labware, pipettes, modules and steps, runs go through the real status lifecycle, and module temperatures respond to the protocol.

Connect your robot

1. Find the IP address: Opentrons App > Devices > your robot > Robot settings > Networking (or on the Flex touchscreen: Settings > Network). The robot must be on the same network as the computer running the MCP server. USB-connected robots also get an IP address (OT-2: 169.254.x.x).
2. Test the connection:
   bash

   uvx labmcp-opentrons --address 192.168.1.20 --checkuvx labmcp-opentrons --address http://ot2-lab.local:31950 --check

   --check prints the robot's name, model, software and firmware versions.
3. Access control (Flex only, rarely needed): if your Flex has access control enabled and requests fail with HTTP 401, pass a token with --option access_token=<token>.

Add to your MCP client

Claude Code

claude mcp add opentrons -- uvx labmcp-opentrons --address 192.168.1.20

Claude Desktop / Cursor / Windsurf (claude_desktop_config.json, .cursor/mcp.json, …)

{  "mcpServers": {    "opentrons": {      "command": "uvx",      "args": ["labmcp-opentrons", "--address", "192.168.1.20"]    }  }}

Add --read-only to let the agent monitor the robot (status, runs, protocols, modules) while blocking uploads, runs, homing and lights. pause_run, stop_run and deactivate_modules stay available. For other clients, generate the snippet with uvx labmcp config opentrons --address 192.168.1.20 --client vscode (also cursor, codex, claude-code).

Tools

get_connection_info, get_command_log and reconnect are built into every LabMCP server. get_command_log shows every HTTP request sent to the robot and its reply.

Safety limits

The defaults are the hardware maxima. Tighten them for heat-sensitive plastics or samples: --limit max_module_temperature_c=70 --limit max_shake_speed_rpm=1500. The check reads the setpoints from the robot's analysis of the protocol (every celsius and rpm value in module commands, including thermocycler profiles).

Other safety interlocks built into start_run:

• the robot's analysis must have completed with result ok (pending, failed or parameter-required analyses are refused, and the errors are shown);
• deck_confirmed=true is required, which the agent should only pass after you confirmed the deck matches the layout from get_protocol;
• no other run may be active, the Flex door must be closed and the E-stop released.

Example prompts

• "Upload ~/protocols/serial_dilution.py to the Flex and tell me whether the analysis passed. What labware do I need where?"
• "The deck is set up as you listed. Start the serial dilution run and tell me when it's halfway."
• "What is the robot doing right now? How many steps are left?"
• "Pause the run — I need to top up the reservoir." … "OK, resume."
• "The run says a tip is missing. I've refilled the tip rack in slot C2; continue the run."
• "The PCR finished. Turn off the thermocycler and the heater-shaker, then switch the lights off."

Notes

• Protocols, not single moves. This server runs complete protocols that the robot has analyzed. It deliberately has no tools for individual pipetting or gantry moves (POST /runs/{id}/commands), because without full deck state these can crash pipettes into labware. That may come later behind stricter checks.
• Labware Position Check offsets are not applied. Runs created through the HTTP API do not include the offsets the Opentrons App applies from Labware Position Check. If your setup depends on them, start the run from the App, or set offsets in the protocol (labware.set_offset(...)).
• Run-time parameters use their default values. Protocols that need a value this server cannot give (e.g. a CSV file parameter) are reported as not ready.
• Stopping a run is final: the robot homes and drops tips in the trash. Pausing waits for the current step to finish.
• Error recovery (recent robot software, mainly Flex): when a step fails (e.g. no tip detected), the run waits in awaiting-recovery. resume_run(error_recovery="continue") continues from the robot's actual state and skips the failed step; "assume_false_positive" treats the failure as a false alarm. Only use either after someone has checked the robot.
• Modules stay on after a protocol ends unless the protocol switches them off. deactivate_modules sends the robot's stateless deactivate commands (POST /commands), which the robot only accepts when no run is in progress.
• list_instruments uses GET /instruments, which the robot fully supports on Flex; on an OT-2 it returns pipettes with less detail (no calibration data).
• The HTTP API version is pinned with the Opentrons-Version: 3 header, as in Opentrons' integration examples. Override with --option api_version=4 if needed.

Hardware verification