Opentrons MCP

🚀 Opentrons MCP 服务器

Opentrons MCP 服务器是一款用于 Opentrons 机器人自动化的模型上下文协议（MCP）服务器，同时还提供 API 文档。该工具为 Opentrons Flex 和 OT - 2 机器人提供了全面的 API 文档和直接的机器人控制功能。

✨ 主要特性

API 文档工具

• 搜索端点：按功能、方法或关键字查找 API 端点。
• 端点详情：获取特定 API 端点的全面信息。
• 分类浏览：按功能类别列出端点。
• API 概述：对整个 Opentrons HTTP API 进行高层次概述。

机器人自动化工具

• 协议管理：上传、列出和管理协议文件。
• 运行控制：创建运行任务、启动/停止执行并监控进度。
• 机器人健康状态：检查连接性和系统状态。
• 硬件控制：使机器人回零、控制灯光及执行基本操作。

📦 安装指南

通过 npm 安装（推荐）

npm install -g opentrons-mcp

从源代码安装

git clone https://github.com/yerbymatey/opentrons-mcp.git
cd opentrons-mcp
npm install

📚 详细文档

配置

将以下内容添加到你的 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "opentrons": {
      "command": "opentrons-mcp",
      "args": []
    }
  }
}

如果是从源代码安装的：

{
  "mcpServers": {
    "opentrons": {
      "command": "node",
      "args": ["/path/to/opentrons-mcp/index.js"]
    }
  }
}

可用工具

文档工具

search_endpoints

按功能、方法、路径或关键字搜索 Opentrons HTTP API 端点。

• query（必需）：搜索词。
• method（可选）：按 HTTP 方法过滤（GET、POST、PUT、DELETE、PATCH）。
• tag（可选）：按 API 类别过滤。
• include_deprecated（可选）：包含已弃用的端点。

get_endpoint_details

获取特定 API 端点的全面详细信息。

• method（必需）：HTTP 方法。
• path（必需）：API 端点路径。

list_by_category

列出特定功能类别中的所有端点。

• category（必需）：API 类别（健康状态、控制、协议管理等）。

get_api_overview

获取 Opentrons HTTP API 结构和功能的高层次概述。

自动化工具

upload_protocol

将协议文件上传到 Opentrons 机器人。

• robot_ip（必需）：机器人 IP 地址。
• file_path（必需）：协议文件的路径（.py 或 .json）。
• protocol_kind（可选）："standard" 或 "quick - transfer"（默认："standard"）。
• key（可选）：客户端跟踪键。
• run_time_parameters（可选）：运行时参数值。

get_protocols

列出机器人上存储的所有协议。

• robot_ip（必需）：机器人 IP 地址。
• protocol_kind（可选）：按协议类型过滤。

create_run

在机器人上创建一个新的协议运行任务。

• robot_ip（必需）：机器人 IP 地址。
• protocol_id（必需）：要运行的协议 ID。
• run_time_parameters（可选）：运行时参数值。

control_run

控制运行任务的执行（播放、暂停、停止、恢复）。

• robot_ip（必需）：机器人 IP 地址。
• run_id（必需）：要控制的运行任务 ID。
• action（必需）："play"、"pause"、"stop" 或 "resume - from - recovery"。

get_runs

列出机器人上的所有运行任务。

• robot_ip（必需）：机器人 IP 地址。

get_run_status

获取特定运行任务的详细状态。

• robot_ip（必需）：机器人 IP 地址。
• run_id（必需）：要检查的运行任务 ID。

robot_health

检查机器人的健康状态和连接性。

• robot_ip（必需）：机器人 IP 地址。

control_lights

打开或关闭机器人的灯光。

• robot_ip（必需）：机器人 IP 地址。
• on（必需）：true 表示打开灯光，false 表示关闭。

home_robot

使机器人轴或特定移液器回零。

• robot_ip（必需）：机器人 IP 地址。
• target（可选）："robot" 表示所有轴，"pipette" 表示特定安装位置。
• mount（可选）："left" 或 "right"（如果 target 为 "pipette" 则必需）。

💻 使用示例

与 Claude Desktop 配合使用

该截图展示了在使用 Claude Desktop 询问 Opentrons Flex 机器人当前协议并提供机器人 IP 后，Opentrons MCP 服务器的运行情况。

配置完成后，你可以使用自然语言控制机器人：

上传协议：

Upload the protocol file at /path/to/my_protocol.py to my robot at 192.168.1.100

检查机器人状态：

Check if my robot at 192.168.1.100 is healthy and ready

运行协议：

List all protocols on my robot, then create and start a run for the latest one

监控进度：

Show me the status of run abc123 on my robot

编程式使用

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"
    }
  }
});

🔧 技术细节

要求

• Node.js 18+
• 启用 HTTP API 的 Opentrons 机器人（端口 31950）
• 客户端与机器人之间的网络连接

机器人设置

确保你的 Opentrons 机器人满足以下条件：

1. 与客户端连接到同一网络。
2. 运行机器人软件版本 7.0.0 或更高版本。
3. 可通过端口 31950 访问（HTTP API 默认端口）。

你可以在浏览器中访问 http://your-robot-ip:31950/health 来验证连接性。

API 参考

该工具可访问完整的 Opentrons HTTP API，包括：

• 协议管理：上传、分析和管理协议文件。
• 运行管理：创建、控制和监控协议运行任务。
• 硬件控制：机器人移动、回零、照明和校准。
• 系统管理：健康监控、设置和诊断。
• 模块控制：温度模块、磁性模块、热循环仪。
• 数据管理：用于运行时参数的 CSV 文件。

如需详细的 API 文档，请使用此 MCP 服务器提供的搜索和文档工具。

故障排除

无法连接到机器人

• 验证机器人 IP 地址是否正确。
• 确保机器人已通电并连接到网络。
• 检查端口 31950 是否可访问。
• 确认机器人软件正在运行。

协议上传失败

• 验证文件路径是否存在且可读。
• 确保协议文件是有效的 Python（.py）或 JSON 格式。
• 检查机器人上的可用磁盘空间。
• 确认协议与机器人类型（OT - 2 或 Flex）兼容。

运行执行问题

• 验证所有必需的实验器具和模块是否已连接。
• 检查机器人校准状态。
• 确保协议分析已成功完成。
• 确认没有硬件错误或冲突。

🤝 贡献

欢迎贡献代码！请随时提交问题和拉取请求。

📄 许可证

未指定许可证，可自由使用。

🔗 相关项目

• Opentrons API 文档
• Model Context Protocol
• Claude Desktop