microduck-mcp 🦆

모든 MCP 클라이언트 — Claude Code, Claude Desktop, 또는 자체 에이전트 — 에서 Pollen Robotics Microduck을 구동하세요. 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

설치

두 개의 공식 저장소의 클론(scenes/policy-runner와 번들된 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

셸에서 호출해 보세요:

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 스키마, 필드별 단위 문서화)을 내보냅니다. 모든 변경 도구는 동작 후 상태를 반환하므로 에이전트가 후속 폴링을 할 필요가 거의 없습니다.

AX 디버그 페이지

duck-sim은 http://127.0.0.1:8400에서 Agent Experience 디버그 페이지도 제공합니다(--web PORT, 비활성화하려면 --web 0): 제어 소켓에 도달하는 모든 명령의 실시간 피드 — 클라이언트별(mcp, cli, web) 태그 — 와 자동 새로고침 카메라 뷰 및 상태 대시보드가 함께 표시됩니다. MuJoCo 뷰어 옆에 열어 에이전트가 무엇을 하고 있고 무엇을 볼 수 있는지 실시간으로 확인하세요. 순수 stdlib HTTP + HTML 파일 하나로 구성되며, 모든 렌더링은 여전히 다른 모든 클라이언트와 동일한 인텐트 큐를 통해 시뮬레이션 스레드에서 이루어집니다.

참고

• 시뮬레이션 서버는 모든 MuJoCo 호출을 단일 스레드에서 실행합니다. 소켓 클라이언트는 인텐트를 큐에 넣기만 합니다. 여러 클라이언트(MCP + CLI 동시)도 문제없습니다.

• 폴리시는 로봇에서와 똑같이 공유된 61차원 관측 계약 뒤에서 핫스왑됩니다: 주행은 걷기 폴리시를 활성화하고, 제로 명령은 기립으로 복귀하며, 에피소드형 트릭은 타임아웃되어 기립으로 돌아갑니다.

• 카메라 렌더링은 오프스크린으로 수행됩니다(창 불필요). macOS의 --viewer 모드에서는 오프스크린 렌더링을 사용할 수 없을 수 있습니다 — 프레임이 필요하면 헤드리스로 실행하세요.

• 번들된 폴리시 세트에는 StandUp 폴리시가 포함되어 있지 않으므로 옆으로 넘어진 오리(예: 거친 롤라드 착지 후)는 그 자리에 남게 됩니다 — duck_reset이 탈출구입니다. StandUp 폴리시를 하나 훈련시키는 것(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입니다.