Opentrons MCP Server

Instructions

Implementation Reference

• index.js:1718-1764 (handler)

  The handler function that implements the create_run tool logic by making a POST request to the Opentrons robot's /runs endpoint to create a new protocol run.
  async createRun(args) { const { robot_ip, protocol_id, run_time_parameters } = args; try { const body = { data: { protocolId: protocol_id } }; if (run_time_parameters) { body.data.runTimeParameterValues = run_time_parameters; } const data = await this.makeApiRequest( 'POST', `http://${robot_ip}:31950/runs`, { 'Content-Type': 'application/json' }, JSON.stringify(body) ); const run = data.data; return { content: [ { type: "text", text: `✅ Run created successfully!\n\n` + `**Run ID:** ${run.id}\n` + `**Status:** ${run.status}\n` + `**Protocol ID:** ${run.protocolId}\n` + `**Created:** ${new Date(run.createdAt).toLocaleString()}\n\n` + `Use the run ID to control execution (play/pause/stop).` } ] }; } catch (error) { return { content: [ { type: "text", text: `❌ Failed to create run: ${error.message}` } ] }; } }
• index.js:139-150 (schema)

  Input schema definition for the create_run tool, specifying parameters robot_ip, protocol_id (required), and optional run_time_parameters.
  name: "create_run", description: "Create a new protocol run on the robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, protocol_id: { type: "string", description: "ID of protocol to run" }, run_time_parameters: { type: "object", description: "Optional runtime parameter values" } }, required: ["robot_ip", "protocol_id"] } },
• index.js:254-255 (registration)

  Registration/dispatch of the create_run tool in the CallToolRequestSchema request handler switch statement.
  case "create_run": return this.createRun(args);
• index.js:31-236 (registration)

  Tool list registration including the create_run tool schema in the ListToolsRequestSchema handler.
  this.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "search_endpoints", description: "Search Opentrons HTTP API endpoints by functionality, method, path, or any keyword", inputSchema: { type: "object", properties: { query: { type: "string", description: "Search query - searches across endpoint names, descriptions, paths, and tags" }, method: { type: "string", description: "HTTP method filter (GET, POST, PUT, DELETE, PATCH)", enum: ["GET", "POST", "PUT", "DELETE", "PATCH"] }, tag: { type: "string", description: "Filter by API category/tag" }, include_deprecated: { type: "boolean", description: "Include deprecated endpoints in results", default: false } }, required: ["query"] } }, { name: "get_endpoint_details", description: "Get comprehensive details about a specific API endpoint", inputSchema: { type: "object", properties: { method: { type: "string", description: "HTTP method (GET, POST, etc.)" }, path: { type: "string", description: "API endpoint path" } }, required: ["method", "path"] } }, { name: "list_by_category", description: "List all endpoints in a specific functional category", inputSchema: { type: "object", properties: { category: { type: "string", description: "API category/tag to filter by", enum: [ "Health", "Networking", "Control", "Settings", "Modules", "Pipettes", "Calibration", "Run Management", "Protocol Management", "Data files Management", "Simple Commands", "Flex Deck Configuration", "Error Recovery Settings", "Attached Modules", "Attached Instruments", "Labware Offset Management", "System Control", "Client Data", "Maintenance Run Management", "Robot", "Subsystem Management" ] } }, required: ["category"] } }, { name: "get_api_overview", description: "Get high-level overview of the Opentrons HTTP API structure and capabilities", inputSchema: { type: "object", properties: {}, additionalProperties: false } }, { name: "upload_protocol", description: "Upload a protocol file to an Opentrons robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address (e.g., '192.168.1.100')" }, file_path: { type: "string", description: "Path to protocol file (.py or .json)" }, protocol_kind: { type: "string", enum: ["standard", "quick-transfer"], default: "standard" }, key: { type: "string", description: "Optional client tracking key (~100 chars)" }, run_time_parameters: { type: "object", description: "Optional runtime parameter values" } }, required: ["robot_ip", "file_path"] } }, { name: "get_protocols", description: "List all protocols stored on the robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, protocol_kind: { type: "string", enum: ["standard", "quick-transfer"], description: "Filter by protocol type (optional)" } }, required: ["robot_ip"] } }, { name: "create_run", description: "Create a new protocol run on the robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, protocol_id: { type: "string", description: "ID of protocol to run" }, run_time_parameters: { type: "object", description: "Optional runtime parameter values" } }, required: ["robot_ip", "protocol_id"] } }, { name: "control_run", description: "Control run execution (play, pause, stop, resume)", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, run_id: { type: "string", description: "Run ID to control" }, action: { type: "string", enum: ["play", "pause", "stop", "resume-from-recovery"], description: "Action to perform" } }, required: ["robot_ip", "run_id", "action"] } }, { name: "get_runs", description: "List all runs on the robot", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" } }, required: ["robot_ip"] } }, { name: "get_run_status", description: "Get detailed status of a specific run", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, run_id: { type: "string", description: "Run ID to check" } }, required: ["robot_ip", "run_id"] } }, { name: "robot_health", description: "Check robot health and connectivity", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" } }, required: ["robot_ip"] } }, { name: "control_lights", description: "Turn robot lights on or off", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, on: { type: "boolean", description: "True to turn lights on, false to turn off" } }, required: ["robot_ip", "on"] } }, { name: "home_robot", description: "Home robot axes or specific pipette", inputSchema: { type: "object", properties: { robot_ip: { type: "string", description: "Robot IP address" }, target: { type: "string", enum: ["robot", "pipette"], default: "robot", description: "What to home" }, mount: { type: "string", enum: ["left", "right"], description: "Which mount (required if target is 'pipette')" } }, required: ["robot_ip"] } }, { name: "poll_error_endpoint_and_fix", description: "Fetch specific JSON error report and automatically fix protocols", inputSchema: { type: "object", properties: { json_filename: { type: "string", default: "error_report_20250622_124746.json", description: "Name of JSON file to fetch" }, original_protocol_path: { type: "string", default: "/Users/gene/Developer/failed-protocol-5.py", description: "Path to original protocol file" } } } } ] }; });
• index.js:1476-1503 (helper)

  Helper method makeApiRequest used by createRun and other tools to perform HTTP requests to the Opentrons robot API.
  async makeApiRequest(method, url, headers = {}, body = null) { try { const options = { method, headers: { 'Opentrons-Version': '*', ...headers } }; if (body) { options.body = body; } const response = await fetch(url, options); const data = await response.json(); if (!response.ok) { throw new Error(`API Error ${response.status}: ${data.message || JSON.stringify(data)}`); } return data; } catch (error) { if (error.code === 'ECONNREFUSED') { throw new Error(`Cannot connect to robot. Please check the IP address and ensure the robot is powered on.`); } throw error; }