Opentrons MCP Server
Hosts the source code repository for the Opentrons MCP server that can be cloned for installation from source.
Supported as a platform for running the MCP server, with specific configuration file paths provided for macOS users.
Serves as the runtime environment for the MCP server, with Node.js 18+ listed as a requirement for running the server.
Provides package management for installing the Opentrons MCP server via the recommended installation method.
Supports protocol files written in Python format (.py) that can be uploaded and executed on Opentrons robots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Opentrons MCP Server check if my robot at 192.168.1.100 is healthy and ready"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Opentrons MCP Server
A Model Context Protocol (MCP) server for Opentrons robot automation and API documentation. This tool provides both comprehensive API documentation and direct robot control capabilities for Opentrons Flex and OT-2 robots.
Features
API Documentation Tools
Search Endpoints: Find API endpoints by functionality, method, or keyword
Endpoint Details: Get comprehensive information about specific API endpoints
Category Browsing: List endpoints by functional category
API Overview: 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, monitor progress
Robot Health: Check connectivity and system status
Hardware Control: Home robot, control lights, and basic operations
Related MCP server: MCP Documentation Server
Installation
From npm (recommended)
npm install -g opentrons-mcpFrom source
git clone https://github.com/yerbymatey/opentrons-mcp.git
cd opentrons-mcp
npm installConfiguration
Add 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 termmethod(optional): Filter by HTTP method (GET, POST, PUT, DELETE, PATCH)tag(optional): Filter by API categoryinclude_deprecated(optional): Include deprecated endpoints
get_endpoint_details
Get comprehensive details about a specific API endpoint.
method(required): HTTP methodpath(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 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 addressfile_path(required): Path to protocol file (.py or .json)protocol_kind(optional): "standard" or "quick-transfer" (default: "standard")key(optional): Client tracking keyrun_time_parameters(optional): Runtime parameter values
get_protocols
List all protocols stored on the robot.
robot_ip(required): Robot IP addressprotocol_kind(optional): Filter by protocol type
create_run
Create a new protocol run on the robot.
robot_ip(required): Robot IP addressprotocol_id(required): ID of protocol to runrun_time_parameters(optional): Runtime parameter values
control_run
Control run execution (play, pause, stop, resume).
robot_ip(required): Robot IP addressrun_id(required): Run ID to controlaction(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 addressrun_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 addresson(required): true to turn lights on, false to turn off
home_robot
Home robot axes or specific pipette.
robot_ip(required): Robot IP addresstarget(optional): "robot" for all axes, "pipette" for specific mountmount(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.100Check robot status:
Check if my robot at 192.168.1.100 is healthy and readyRun a protocol:
List all protocols on my robot, then create and start a run for the latest oneMonitor progress:
Show me the status of run abc123 on my robotProgrammatic 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:
Connected to the same network as your client
Running robot software version 7.0.0+
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 robot IP address is correct
Ensure robot is powered on and connected to network
Check that port 31950 is accessible
Confirm robot software is running
Protocol upload fails
Verify file path exists and is readable
Ensure protocol file is valid Python (.py) or JSON format
Check available disk space on robot
Confirm protocol is compatible with robot type (OT-2 vs Flex)
Run execution issues
Verify all required labware and modules are attached
Check robot calibration status
Ensure protocol analysis completed successfully
Confirm 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
Available Tools
14 toolscontrol_lightsC
Turn robot lights on or off
Inputs: robot_ip (required), on (required).
control_runC
Control run execution (play, pause, stop, resume)
Inputs: robot_ip (required), run_id (required), action (required).
create_runC
Create a new protocol run on the robot
Inputs: robot_ip (required), protocol_id (required), run_time_parameters.
get_api_overviewB
Get high-level overview of the Opentrons HTTP API structure and capabilities
Inputs: no named parameters.
get_endpoint_detailsC
Get comprehensive details about a specific API endpoint
Inputs: method (required), path (required).
get_protocolsC
List all protocols stored on the robot
Inputs: robot_ip (required), protocol_kind.
get_runsB
List all runs on the robot
Inputs: robot_ip (required).
get_run_statusC
Get detailed status of a specific run
Inputs: robot_ip (required), run_id (required).
home_robotC
Home robot axes or specific pipette
Inputs: robot_ip (required), target, mount.
list_by_categoryC
List all endpoints in a specific functional category
Inputs: category (required).
poll_error_endpoint_and_fixC
Fetch specific JSON error report and automatically fix protocols
Inputs: json_filename, original_protocol_path.
robot_healthC
Check robot health and connectivity
Inputs: robot_ip (required).
search_endpointsC
Search Opentrons HTTP API endpoints by functionality, method, path, or any keyword
Inputs: query (required), method, tag, include_deprecated.
upload_protocolC
Upload a protocol file to an Opentrons robot
Inputs: robot_ip (required), file_path (required), protocol_kind, key, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 14 tools
Most tools have distinct purposes, but there is some overlap between get_endpoint_details, list_by_category, and search_endpoints, which all relate to API endpoint discovery and could cause confusion. Additionally, poll_error_endpoint_and_fix combines error fetching and fixing in one tool, which might overlap with general run control functions.
The naming follows a consistent verb_noun pattern (e.g., control_lights, create_run, get_protocols) with only minor deviations like poll_error_endpoint_and_fix being more descriptive and robot_health as a noun phrase. Overall, it's readable and mostly predictable.
With 14 tools, this is well-scoped for managing an Opentrons robot, covering protocol handling, run control, robot operations, and API exploration. Each tool appears to serve a specific function without being excessive.
The tool set covers core robot operations (lights, homing, health), protocol lifecycle (upload, list, create runs), and run management (control, status). A minor gap is the lack of a tool for deleting or modifying protocols, but agents can likely work around this.
Related MCP Connectors
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
The Fireflies MCP Server enables AI tools to connect directly to meeting data from Fireflies.ai, providing access to meeting transcripts, summaries, action items, and insights without switching platforms. It includes capabilities for querying cross-meeting data for analysis (such as sales insights or product feedback), and a separate Documentation MCP Server that allows searching the Fireflies knowledge base for API references, guides, and code examples.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceServer that ingests Swagger/OpenAPI specifications and Postman collections, providing just 4 strategic tools that allow AI agents to dynamically discover and interact with APIs instead of generating hundreds of individual tools.3ISC
- AlicenseNot gradedqualityDmaintenanceA server that provides organized documentation content for various applications using the Model Context Protocol, enabling AI assistants to access quickstart guides and code examples.MIT
- AlicenseNot gradedqualityDmaintenanceA sophisticated server that enables AI assistants to automatically analyze codebases and generate comprehensive, professional documentation.2MIT
- FlicenseNot gradedqualityDmaintenanceA sophisticated AI-powered server providing intelligent, context-aware conversational capabilities with role-based advisors, semantic memory, multi-LLM support, and web browsing.1-