Opentrons MCP Server

Instructions

Implementation Reference

• index.js:1817-1869 (handler)

  The main handler function for the 'get_runs' tool. Fetches the list of protocol runs from the Opentrons robot API at /runs, formats them nicely, and returns up to 10 recent runs with status, creation time, protocol ID, and duration.

  async getRuns(args) {
    const { robot_ip } = args;
    
    try {
      const data = await this.makeApiRequest(
        'GET',
        `http://${robot_ip}:31950/runs`
      );
      
      const runs = data.data || [];
      
      if (runs.length === 0) {
        return {
          content: [
            {
              type: "text",
              text: `No runs found on robot.`
            }
          ]
        };
      }
      
      const runList = runs.slice(0, 10).map(r => {
        const duration = r.completedAt && r.startedAt
          ? Math.round((new Date(r.completedAt) - new Date(r.startedAt)) / 1000 / 60)
          : null;
          
        return `**Run ${r.id}**\n` +
               `  Status: ${r.status}\n` +
               `  Created: ${new Date(r.createdAt).toLocaleString()}\n` +
               `  Protocol: ${r.protocolId || 'None'}\n` +
               `  Duration: ${duration ? `${duration} minutes` : 'N/A'}\n`;
      }).join('\n');
      
      return {
        content: [
          {
            type: "text",
            text: `Found ${runs.length} run${runs.length !== 1 ? 's' : ''} on robot${runs.length > 10 ? ' (showing latest 10)' : ''}:\n\n${runList}`
          }
        ]
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `❌ Failed to get runs: ${error.message}`
          }
        ]
      };
    }
  }

• index.js:167-173 (schema)

  Input schema definition for the get_runs tool. Requires 'robot_ip' parameter.

  inputSchema: {
    type: "object",
    properties: {
      robot_ip: { type: "string", description: "Robot IP address" }
    },
    required: ["robot_ip"]
  }

• index.js:164-174 (registration)

  Tool registration in the ListToolsRequestSchema handler, defining name, description, and input schema for get_runs.

  {
    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"]
    }
  },

• index.js:258-259 (registration)

  Registration and dispatch of get_runs handler in the CallToolRequestSchema switch statement.

  case "get_runs":
    return this.getRuns(args);