microduck-mcp 🦆

Pollen Robotics Microduck を、あらゆる MCP クライアント（Claude Code、Claude Desktop、独自エージェント）から操作します。AI は、アヒルを歩かせたり、トリックを実行させたり、押したり、レンダリングされたカメラフレームを通して見るためのツールを手に入れます。

現在はシミュレートされたアヒル（公式の事前学習済み ONNX ポリシーを実行する CPU MuJoCo、pollen-robotics/microduck 由来）を操作します。コントロールプレーンはインテントのみ（速度、トリック、視線）で、実機の robotd コントラクトを反映しているため、アヒルが届いたら同じツールの背後にハードウェアバックエンドを組み込めます。

すべてのフレームは duck_camera ツールによってレンダリングされています。これはまさに AI が運転中に見ているものです。

アーキテクチャ

MCP client (Claude, ...)   duck CLI (humans / scripts)   browser: AX debug page
        │ stdio                          │                        │ http :8400
        ▼                                ▼                        ▼
   duck-mcp  ────────────►  Unix socket, JSON lines  ◄────  built-in web UI
                                    │
                                    ▼
                          duck-sim (50 Hz MuJoCo loop,
                          ONNX policy hot-swapping via
                          microduck_rl's PolicyInference)

設計の根拠（ツールとリソース、構造化出力、エラーセマンティクス）は docs/mcp-design-notes.md に文書化されています。

Related MCP server: MuJoCo MCP Server

セットアップ

公式リポジトリ2つ（シーン/ポリシーランナー用と同梱の ONNX ポリシー用）のクローンと、uv が必要です:

git clone https://github.com/pollen-robotics/microduck
git clone https://github.com/pollen-robotics/microduck_rl
git clone https://github.com/aj-dev-smith/microduck-mcp
cd microduck-mcp && uv sync

実行

シミュレーションサーバーを起動します（デフォルトでは3つのリポジトリが兄弟ディレクトリにあると想定）:

uv run duck-sim --rl-repo ../microduck_rl --policies ../microduck/policies

デフォルトはヘッドレスです。MuJoCo ビューアで見るには（macOS では mjpython が必要）:

uv run mjpython -m microduck_mcp.sim_server --viewer \
    --rl-repo ../microduck_rl --policies ../microduck/policies

シェルから試してみます:

uv run duck state
uv run duck drive 0.2          # walk forward at 0.2 m/s
uv run duck trick roulade      # forward roll
uv run duck cam follow         # render a frame, prints the PNG path
uv run duck push               # shove it, watch it recover

MCP サーバーを Claude Code に登録します:

claude mcp add duck -- uv --directory /path/to/microduck-mcp run duck-mcp

MCP ツール

状態を返すすべてのツールは、型付きの構造化出力（DuckState スキーマ、単位はフィールドごとに記載）を出力します。状態を変更するすべてのツールは操作後の状態を返すため、エージェントが追加でポーリングする必要はほとんどありません。

AX デバッグページ

duck-sim は http://127.0.0.1:8400 で Agent Experience デバッグページも提供します（--web PORT、無効化は --web 0）。コントロールソケットに届くすべてのコマンドのライブフィード（クライアント mcp、cli、web でタグ付け）が、自動更新されるカメラビューと状態ダッシュボードの隣に表示されます。MuJoCo ビューアの横に開いて、エージェントが何をしているか、何を見ているかをリアルタイムで確認できます。標準ライブラリの HTTP + HTML ファイル1つだけです。レンダリングはすべて、他のクライアントと同じインテントキューを介してシミュレーションスレッド上で行われます。

注記

• シミュレーションサーバーはすべての MuJoCo 呼び出しを1つのスレッドで実行します。ソケットクライアントはインテントをエンキューするだけです。複数クライアント（MCP + CLI の同時使用）も問題ありません。

• ポリシーは、実機と同じ共有の61次元観測コントラクトの背後でホットスワップされます。駆動で歩行が開始され、ゼロコマンドで立位に戻り、エピソード型トリックはタイムアウトで立位に戻ります。

• カメラレンダリングはオフスクリーンです（ウィンドウ不要）。macOS の --viewer モードではオフスクリーンレンダリングが利用できない場合があります。フレームが必要な場合はヘッドレスで実行してください。

• 同梱のポリシーセットには StandUp ポリシーが含まれていないため、横向きに倒れたアヒル（例: 乱暴な roulade 着地の後）はそのままになります。duck_reset が逃げ道です。StandUp ポリシーの学習（microduck_rl の Mjlab-StandUp-*）が修正策です。

ロードマップ

• 同じツールの背後で、デーモンの WebSocket API（microduck ドキュメントの design/architecture.md §5.3 を参照）を話す実機ロボットバックエンド

• 体の姿勢インテント（立位でのしゃがみ/リーン）

• オプションの StandUp ポリシースロット。duck_reset なしで転倒から回復可能に

ライセンス

Apache-2.0。microduck と microduck_rl（Pollen Robotics 製、ともに Apache-2.0）をベースに構築されています。