Opentrons OT-2 / Flex

Opentrons OT-2 / Flex — MCP 服务

让 AI Agent 通过机器人有文档说明的 HTTP API，在 Opentrons Flex 和 OT-2 液体处理机器人上上传和检查协议、与你一起查看工作台布局、启动、暂停、停止和恢复运行、跟踪运行进度，以及读取移液器和模块信息。

软件包	labmcp-opentrons
仪器	Opentrons Flex、Opentrons OT-2（机器人软件 5.1 或更高版本）
接口	以太网、Wi-Fi、USB（通过 USB 建立网络连接）
协议	Opentrons 机器人服务器 HTTP API，端口 31950，Opentrons-Version: 3（HTTP API 指南，robot-server 源码；每台机器人也会在 http://<robot-ip>:31950/openapi.json 和 /redoc 提供其规范）
状态	🧪 模拟：已通过内存中的 robot-server 模拟器测试，尚未在硬件上验证。报告硬件测试结果

为什么要用此服务，而不是通用的 HTTP 包装器：只有在机器人自身的协议分析通过、用户已确认工作台、舱门已关闭、急停已解除且模块设定值处于你的限制范围内时，它才允许启动运行。它不提供单步移液命令；即使在只读模式下，暂停和停止功能仍可用，并且会在命令日志中记录每个 HTTP 请求。

无需硬件即可试用

uvx labmcp-opentrons --simulate --check
uvx labmcp-opentrons --simulate --option sim_model=ot2 --check   # simulate an OT-2

模拟器会在内存中运行协议：Python 协议会被编译并扫描，以识别实验室器具、移液器、模块和步骤；运行会经历真实的状态生命周期，模块温度也会根据协议变化。

连接机器人

1. 查找 IP 地址： Opentrons App > Devices > 你的机器人 > Robot settings > Networking（或在 Flex 触摸屏上：Settings > Network）。机器人必须与运行 MCP 服务的计算机连接到同一网络。通过 USB 连接的机器人也会获得 IP 地址（OT-2：169.254.x.x）。
2. 测试连接：

   uvx labmcp-opentrons --address 192.168.1.20 --check
   uvx labmcp-opentrons --address http://ot2-lab.local:31950 --check
   

   --check 会显示机器人的名称、型号、软件和固件版本。
3. **访问控制（仅限 Flex，通常不需要）：**如果你的 Flex 启用了访问控制，且请求因 HTTP 401 失败，请使用 --option access_token=<token> 传入令牌。

添加到你的 MCP 客户端

Claude Code

claude mcp add opentrons -- uvx labmcp-opentrons --address 192.168.1.20

Claude Desktop / Cursor / Windsurf（claude_desktop_config.json、.cursor/mcp.json、…）

{
  "mcpServers": {
    "opentrons": {
      "command": "uvx",
      "args": ["labmcp-opentrons", "--address", "192.168.1.20"]
    }
  }
}

添加 --read-only，即可让 Agent 监控机器人（状态、运行、协议、模块），同时阻止上传、运行、回原点和灯光控制。pause_run、stop_run 和 deactivate_modules 仍可使用。对于其他客户端，可使用 uvx labmcp config opentrons --address 192.168.1.20 --client vscode 生成配置片段（也支持 cursor、codex、claude-code）。

工具

工具	类型	描述
deactivate_modules	🛑 safety	关闭已连接的模块：停止加热／制冷（Temperature Module、Thermocycler 模块和盖子、Heater-Shaker 加热器），停止振荡，并降低 Magnetic Module 磁铁。仅在没有运行正在进行时可执行：请先停止运行。
get_command_log	👁 read	返回最近发送给仪器的原始命令／收到的回复（最新的排在最后）。便于调试和记录已执行的操作。
get_connection_info	👁 read	报告已连接的仪器（标识、地址、模拟或真实）、服务是否为只读，以及当前的安全限制。请先调用此工具。
get_protocol	👁 read	显示已存储协议的分析结果：是否可运行、分析错误、所需的载台布局（每个槽位的实验室耗材和模块、每个安装位的移液器、液体）、步骤数，以及所请求的最高模块温度／振荡速度。请在调用 start_run 前与用户一起检查。
get_robot_status	👁 read	报告机器人的名称、型号（Flex/OT-2）、软件和固件版本、指示灯、舱门和 E-stop 状态，以及当前运行。请先调用此工具，检查机器人是否已准备就绪。
get_run_status	👁 read	报告运行状态、当前步骤、进度、最近步骤和任何错误，并提供下一步操作建议（例如运行等待错误恢复时该怎么做）。
home_robot	⚠️ hazard	将机器人的所有轴归位（龙门架和移液器会移动到归位位置）。运行期间拒绝执行。请确保机器人移动路径上没有障碍物，并且舱门已关闭。
list_instruments	👁 read	列出已连接的移液器（以及 Flex 夹爪）：安装位、名称、通道数、体积范围，以及是否检测到吸头和是否存在校准数据。
list_modules	👁 read	列出已连接的模块（Temperature Module、Heater-Shaker、Thermocycler、Magnetic Module、Absorbance Plate Reader 等）及其实时温度、目标值、振荡速度和状态。
list_protocols	👁 read	列出机器人上存储的协议（最新的排在最后）及其分析状态和结果。
list_runs	👁 read	列出最近的协议运行，按最新优先排序，并显示其状态。
pause_run	🛑 safety	暂停正在运行的协议。机器人会完成当前步骤，然后暂停等待；调用 resume_run 可继续运行。
reconnect	🛑 safety	关闭并重新打开与仪器的连接（例如仪器断电重启或重新插接电缆后）。
resume_run	⚠️ hazard	恢复已暂停的运行（机器人将重新开始移动），或退出错误恢复状态。舱门打开时拒绝执行。对于等待恢复的运行，必须提供 error_recovery。
set_lights	🎛 control	打开或关闭机器人的载台（导轨）灯。
start_run	⚠️ hazard	创建已分析协议的运行并启动：机器人将开始移动并进行移液。仅当协议分析已完成且没有错误、模块设定值在安全限制范围内、没有其他运行处于活动状态、舱门已关闭且 E-stop 已解除时才会执行。
stop_run	🛑 safety	立即停止（取消）运行。已停止的运行无法恢复；机器人会归位，并将所有已安装的吸头丢入废料盒。发现异常时请使用此工具。
upload_protocol	🎛 control	将协议文件（以及可选的自定义实验室耗材）上传到机器人。机器人会对其进行分析（模拟），此工具会返回分析结果：错误、载台布局以及协议是否可运行。上传不会使机器人移动。上传相同文件时会返回现有协议。

get_connection_info、get_command_log 和 reconnect 内置于每个 LabMCP 服务中。get_command_log 会显示发送给机器人的每个 HTTP 请求及其回复。

安全限制

限制	默认值	含义
max_module_temperature_c	110 °C	协议可请求的最高温度（温控模块、热循环仪模块或盖子、加热振荡器）；超过此值的协议会被 start_run 拒绝
max_shake_speed_rpm	3000 rpm	协议可请求的最高加热振荡器转速

默认值为硬件上限。对于热敏塑料或样品，请调低这些限制：--limit max_module_temperature_c=70 --limit max_shake_speed_rpm=1500。检查会读取机器人对协议的分析结果中的设定值（模块命令中的每个 celsius 和 rpm 值，包括热循环仪程序）。

start_run 内置的其他安全联锁：

• 机器人必须已完成分析，且结果为 ok（待处理、失败或需要参数的分析都会被拒绝，并显示错误）；
• 必须设置 deck_confirmed=true，Agent 只能在你确认机架布局与 get_protocol 返回的布局一致后才传入此值；
• 不得有其他运行正在进行，Flex 舱门必须关闭，且急停按钮必须已释放。

提示词示例

• “将 ~/protocols/serial_dilution.py 上传到 Flex，并告诉我分析是否通过。各个位置需要放什么实验器材？”
• “机架已按你列出的方式设置。开始运行序列稀释程序，并在运行到一半时告诉我。”
• “机器人现在在做什么？还剩多少步？”
• “暂停运行——我需要补充储液槽。”……“好了，继续运行。”
• “运行提示缺少吸头。我已在 C2 槽位的吸头架中补满吸头；继续运行。”
• “PCR 已完成。关闭热循环仪和加热振荡器，然后关灯。”

备注

• 运行完整协议，而非单个动作。 此服务运行的是机器人已分析过的完整协议。它特意不提供单独移液或龙门架移动的工具（POST /runs/{id}/commands），因为缺少完整的机架状态可能导致移液器撞上实验器材。以后可能会在加入更严格的检查后提供这些功能。
• 不会应用实验器材位置检查偏移量。 通过 HTTP API 创建的运行不会包含 Opentrons App 根据实验器材位置检查应用的偏移量。如果你的设置依赖这些偏移量，请从 App 启动运行，或在协议中设置偏移量（labware.set_offset(...)）。
• 运行时参数使用默认值。若协议需要此服务无法提供的值（例如 CSV 文件参数），则会报告为尚未就绪。
• 停止运行不可撤销：机器人会回原点，并将吸头丢入废料桶。暂停则会等待当前步骤完成。
• 错误恢复（较新的机器人软件，主要是 Flex）：步骤失败时（例如未检测到吸头），运行会停在 awaiting-recovery 状态。resume_run(error_recovery="continue") 会从机器人的实际状态继续，并跳过失败的步骤；"assume_false_positive" 会将故障视为误报。只有在有人检查过机器人后，才能使用其中任一选项。
• 协议结束后，模块会保持开启状态，除非协议将其关闭。deactivate_modules 会发送机器人的无状态停用命令（POST /commands）；只有在没有运行进行时，机器人才会接受这些命令。
• list_instruments 使用 GET /instruments；机器人在 Flex 上完全支持此接口，在 OT-2 上则只会返回详细信息较少的移液器（不含校准数据）。
• HTTP API 版本通过 Opentrons-Version: 3 标头固定，如 Opentrons 的集成示例所示。如有需要，可使用 --option api_version=4 覆盖。

硬件验证

型号	机器人软件	接口	验证者	日期
尚无： 成为首位验证者