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