microduck-mcp 🦆

从任意 MCP 客户端驱动 Pollen Robotics Microduck —— Claude Code、Claude Desktop 或你自己的 agent。AI 获得一系列工具，可以带着鸭子四处走动、触发特技、推它，并通过渲染的相机画面看到它。

目前它驱动的是模拟鸭子（CPU 版 MuJoCo 运行来自 pollen-robotics/microduck 的官方预训练 ONNX 策略）。控制面仅包含意图 —— 速度、特技、注视 —— 与真实机器人的 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)

设计原理（工具 vs 资源、结构化输出、错误语义）记录在 docs/mcp-design-notes.md 中。

Related MCP server: MuJoCo MCP Server

安装

需要克隆两个官方仓库（用于场景/策略运行器和随附的 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

运行

启动模拟服务器（默认假设三个仓库是同级目录）：

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

从 shell 中调用它：

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

向 Claude Code 注册 MCP 服务器：

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

MCP 工具

所有返回状态的工具都会输出类型化的结构化结果（DuckState 模式，每个字段都标注了单位）；每个变更工具都会返回操作后的状态，因此 agent 很少需要后续轮询。

AX 调试页面

duck-sim 还在 http://127.0.0.1:8400 提供 Agent Experience 调试页面（--web PORT，--web 0 可禁用）：实时显示到达控制套接字的每条指令 —— 按客户端（mcp、cli、web）标记 —— 旁边是自动刷新的相机视图和状态仪表盘。在 MuJoCo 查看器旁边打开它，即可实时观察agent 在做什么以及它能看到什么。纯标准库 HTTP + 一个 HTML 文件；所有渲染仍然通过与其他客户端相同的意图队列在模拟线程上完成。

备注

• 模拟服务器在单线程上执行所有 MuJoCo 调用；套接字客户端只入队意图。多个客户端可以同时使用（MCP + CLI 同时运行）。

• 策略在共享的 61 维观测契约之后热切换，与机器人上完全一致：驱动时启用行走，零指令回到站立，回合制特技超时后回到站立。

• 相机渲染在离屏进行（无需窗口）；在 macOS 的 --viewer 模式下，离屏渲染可能不可用 —— 如果需要画面，请以无头模式运行。

• 随附的策略集不包含 StandUp 策略，因此一只最终侧倒在地的鸭子（例如在一次粗暴的翻滚落地后）会保持那个状态 —— duck_reset 是逃生舱。训练一个（microduck_rl 中的 Mjlab-StandUp-*）是解决办法。

路线图

• 在同一套工具后面实现真实机器人后端，使用守护进程的 WebSocket API（参见 microduck 文档 design/architecture.md §5.3）

• 身体姿态意图（站立时下蹲/倾斜）

• 可选的 StandUp 策略槽位，使跌倒无需 duck_reset 即可恢复

许可证

Apache-2.0。基于 Pollen Robotics 的 microduck 和 microduck_rl 构建，两者均为 Apache-2.0。