Opentrons API MCP Server

Opentrons HTTP API v2 および Python Protocol API を操作・参照するための TypeScript / Node.js ベースの Model Context Protocol (MCP) サーバーです。
Claude Desktop、Cursor などの MCP クライアントから、Opentrons ロボット（OT-2 / Opentrons Flex）の操作、プロトコルの検証・実行、ステータス確認、ドキュメント検索を行うことができます。

---

主な機能

• 📚 opentrons_search_docs: Opentrons Python Protocol API および HTTP API のドキュメント・サンプルコードを検索
• 🔍 opentrons_validate_protocol: Python プロトコルの構文チェックおよび物理ハードウェア（モジュール/ピペット）の要求照合
• 🚀 opentrons_upload_and_run: ハードウェア検証・プロトコルアップロード・Run 生成・実行開始を安全に一括実行
• 📊 opentrons_get_robot_status: ロボットの接続状態、モジュール/ピペット構成、Run の進捗ステータスを取得
• ⏸️ opentrons_control_run: Run に対する操作（play, pause, stop, resume）
• ⚡ opentrons_execute_command: 個別のハードウェアダイレクトコマンドを発行

---

前提条件

• Node.js: v20.0.0 以上 (動作確認済み: v22.22.0)
• npm: v10.0.0 以上
• Opentrons ロボット: OT-2 または Opentrons Flex（API ポート 31950 が開放されていること）

---

インストール & セットアップ

1. 依存関係のインストール

npm install

2. ドキュメント検索インデックスの構築

npm run build:index

3. プロジェクトのビルド

npm run build

---

環境変数の設定

プロジェクトルートに .env ファイルを作成するか、環境変数を設定して接続先ロボット情報を指定します。

# Opentrons ロボットの IP アドレス (デフォルト: 127.0.0.1)
OPENTRONS_ROBOT_IP=192.168.1.100

# Opentrons HTTP API ポート (デフォルト: 31950)
OPENTRONS_ROBOT_PORT=31950

# API トークン (認証が必要な場合のみ)
OPENTRONS_API_TOKEN=

---

MCP クライアントへの登録方法

Claude Desktop の場合

claude_desktop_config.json（Windows の場合は %APPDATA%\Claude\claude_desktop_config.json）に以下のように追加します。

{
  "mcpServers": {
    "opentrons": {
      "command": "node",
      "args": [
        "C:/path/to/otie-mcp/dist/index.js"
      ],
      "env": {
        "OPENTRONS_ROBOT_IP": "192.168.1.100",
        "OPENTRONS_ROBOT_PORT": "31950"
      }
    }
  }
}

開発モードでの実行 (tsx)

{
  "mcpServers": {
    "opentrons": {
      "command": "npx",
      "args": [
        "tsx",
        "C:/path/to/otie-mcp/src/index.ts"
      ],
      "env": {
        "OPENTRONS_ROBOT_IP": "192.168.1.100",
        "OPENTRONS_ROBOT_PORT": "31950"
      }
    }
  }
}

---

ツール一覧と利用方法

1. opentrons_search_docs

Opentrons API ドキュメントをキーワード検索します。

• パラメータ:
  • query (string, 必須): 検索キーワード（例: "temperature module", "transfer", "load_labware"）
  • maxResults (number, 任意): 最大取得件数（デフォルト: 5）

2. opentrons_validate_protocol

Python プロトコルコードの構文チェックと、接続済みモジュール/ピペットとの適合性をチェックします。

• パラメータ:
  • protocolContent (string, 必須): Python プロトコルコード本文

3. opentrons_upload_and_run

物理ハードウェア検証を行ったうえでプロトコルをアップロードし、Run を生成して実行を開始します。必要なモジュールが不足している場合は安全にブロックされます。

• パラメータ:
  • protocolContent (string, 必須): Python プロトコルコード本文
  • filename (string, 任意): 保存ファイル名（デフォルト: "protocol.py"）

4. opentrons_get_robot_status

ロボットの健康状態、接続中モジュール・ピペット、および特定の Run ステータスを取得します。

• パラメータ:
  • runId (string, 任意): 確認したい Run の ID

5. opentrons_control_run

実行中または一時停止中の Run を制御します。

• パラメータ:
  • runId (string, 必須): 対象の Run ID
  • action (string, 必須): 'play' | 'pause' | 'stop' | 'resume'

6. opentrons_execute_command

指定した Run に対し、ダイレクトコマンド（ホーム復帰、ピペット移動など）を発行します。

• パラメータ:
  • runId (string, 必須): 対象の Run ID
  • commandType (string, 必須): コマンド種別（例: "home", "loadLabware"）
  • params (object, 任意): コマンドパラメータ
  • intent (string, 任意): 'setup' | 'protocol'

---

テストの実行

Jest によるユニットテストを実行します。

npm test

---

ライセンス

ISC License