Opentrons MCP Server

Instructions

Implementation Reference

• index.js:2015-2057 (handler)

  The main handler function for the 'home_robot' tool. It makes a POST request to the Opentrons robot API endpoint '/robot/home' with the provided parameters to home the robot axes or a specific pipette.
  async homeRobot(args) { const { robot_ip, target = "robot", mount } = args; try { const body = { target }; if (target === "pipette" && mount) { body.mount = mount; } const data = await this.makeApiRequest( 'POST', `http://${robot_ip}:31950/robot/home`, { 'Content-Type': 'application/json' }, JSON.stringify(body) ); let message = `✅ `; if (target === "robot") { message += `Robot homed successfully! All axes are at their home positions.`; } else { message += `Pipette on ${mount} mount homed successfully!`; } return { content: [ { type: "text", text: message } ] }; } catch (error) { return { content: [ { type: "text", text: `❌ Failed to home robot: ${error.message}` } ] }; } }
• index.js:210-222 (schema)

  The input schema definition for the 'home_robot' tool, specifying parameters like robot_ip (required), target (robot or pipette), and mount (for pipette). This is returned in the ListTools response.
  { 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"] } },
• index.js:266-267 (registration)

  Registration of the 'home_robot' tool handler in the CallToolRequestSchema switch statement, mapping the tool name to the homeRobot method.
  case "home_robot": return this.homeRobot(args);
• index.js:31-235 (registration)

  The tool is registered in the ListToolsRequestSchema handler by including it in the tools array returned to clients.
  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-1504 (helper)

  Helper method used by homeRobot (and other tools) to make HTTP requests to the Opentrons robot API, handling errors and adding required headers.
  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; } }