Opentrons MCP Server

Instructions

Implementation Reference

• index.js:1766-1815 (handler)

  The main handler function for the 'control_run' tool. It sends a POST request to the Opentrons robot's /runs/{run_id}/actions endpoint with the specified action (play, pause, stop, resume-from-recovery), fetches the updated run status, and returns a formatted response with success or error message.
  async controlRun(args) { const { robot_ip, run_id, action } = args; try { const body = { data: { actionType: action } }; const data = await this.makeApiRequest( 'POST', `http://${robot_ip}:31950/runs/${run_id}/actions`, { 'Content-Type': 'application/json' }, JSON.stringify(body) ); const actionData = data.data; // Get updated run status const runData = await this.makeApiRequest( 'GET', `http://${robot_ip}:31950/runs/${run_id}` ); const run = runData.data; return { content: [ { type: "text", text: `✅ Run action '${action}' executed successfully!\n\n` + `**Action ID:** ${actionData.id}\n` + `**Run Status:** ${run.status}\n` + `**Current Action:** ${run.actions?.[run.actions.length - 1]?.actionType || 'None'}\n` + `**Completed At:** ${run.completedAt ? new Date(run.completedAt).toLocaleString() : 'Not completed'}\n` } ] }; } catch (error) { return { content: [ { type: "text", text: `❌ Failed to control run: ${error.message}` } ] }; } }
• index.js:152-163 (schema)

  Input schema definition for the 'control_run' tool, defining parameters: robot_ip (string), run_id (string), action (enum: play, pause, stop, resume-from-recovery). Included in the tools list returned by ListToolsRequestSchema.
  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"] } },
• index.js:256-257 (registration)

  Registration of the 'control_run' tool handler in the CallToolRequestSchema switch statement, dispatching calls to this.controlRun(args).
  case "control_run": return this.controlRun(args);
• index.js:1476-1504 (helper)

  Helper method used by controlRun (and other tools) to make authenticated HTTP requests to the Opentrons robot API, handling Opentrons-Version header and common errors like connection refused.
  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; } }