microduck-mcp
Control and monitor a Microduck robot (real or simulated) through MCP tools.
Read hardware/software health, version, updates, and state (joints, gravity, odometry, safety flags).
Capture camera views (head, follow, front, side, top) as PNG images.
Walk with velocity intent (vx, vy, wz) for a specified duration.
Trigger behaviors: sit, stand, getup, pickup, kick, roulade, quack.
Stop all motion immediately and unconditionally.
Allows loading Microduck robot policies from Hugging Face Hub repositories into the robot's policy slots.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@microduck-mcp Walk the duck forward slowly for 3 seconds, then stop."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
microduck-mcp 🦆 — by MicroduckHub
The universal agent interface for the Pollen Robotics Microduck.
An MCP (Model Context Protocol) server that lets any AI agent — Claude, ChatGPT, Cursor, Gemini CLI, smolagents — drive a Microduck: walk it, sit it, make it pick things up, read its health, and stop it.
Part of MicroduckHub.

Unscripted: a real Claude Code session choosing its own tool calls against the simulator. The duck plays at real speed; the model's thinking time between calls is sped up 6× and labelled.
Works today with no robot: a mock transport for instant canned state, and a simulator — CPU MuJoCo running Pollen's official pretrained ONNX policies — so agents can walk, sit, kick and look at a physically simulated duck before yours ships.
Quick start
No robot needed. The mock answers instantly; the sim is a physically simulated duck running Pollen's official policies.
npx -y microduck-mcp setup-sim # once, ~1 min: MuJoCo + the official scene and policies (~35 MB)It needs uv (recommended — it fetches the right
Python for you) or Python 3.10–3.13, installs into a per-user directory
(~/.local/share/microduck-mcp/sim on Linux; DUCK_SIM_HOME to move it), and
finishes by starting the sim and rendering a frame, so you know it works. Safe
to re-run: it repairs anything missing or corrupt.
Then point your MCP client at it:
{
"mcpServers": {
"microduck": {
"command": "npx",
"args": ["-y", "microduck-mcp"],
"env": { "DUCK_TRANSPORT": "sim" }
}
}
}"DUCK_TRANSPORT": "mock" skips the setup entirely. That JSON works as-is in
Claude Desktop and Cursor; docs/clients.md has
copy-paste setup for Claude Desktop, Claude Code, Cursor, VS Code, Gemini CLI,
Codex CLI and smolagents, plus why ChatGPT can't connect yet.
On a real duck, use "DUCK_TRANSPORT": "ssh" with "DUCK_HOST": "duck@microduck.local"
from a laptop, or "unix" when running on the robot itself.
From source
npm install
npm run setup-sim # same as above, from the checkout
npm test # safety layer, mock, sim-transport and setup tests
npm run demo # health → walk → monitor → camera → quack → stop (mock)
DUCK_TRANSPORT=sim npm run demo # same, in MuJoCo; frames land in demo-out/If Claude Desktop runs on Windows and the checkout lives in WSL, use
"command": "wsl.exe", "args": ["-e", "bash", "-lc", "DUCK_TRANSPORT=sim node /home/you/microduck-mcp/dist/cli.js"].
Related MCP server: Reachy Mini MCP
Tools
Tool | What it does | Guarded? |
| Battery, temps, loop rate, loaded policy | read-only |
| Robot name, serial, uptime | read-only |
| Installed releases | read-only |
| One-shot state: joints, gravity, gyro, odometry, current intent | read-only |
| PNG frame: the head camera (hardware, via mediad) or follow/front/side/top views (sim) | read-only |
| Which | read-only |
| Hugging Face models matching a query | read-only |
| Fetch an HF repo into the robot's library and swap it into one slot, or load an on-board | gated like motion |
| Remove the override on one slot (or all seven) — the one-word undo for a load | gated like motion |
| Velocity intent (vx/vy/wz) for | clamped, battery-gated, rate-limited |
| sit / stand / getup / pickup / kick / roulade / quack | gated (quack is free; getup allowed while fallen) |
| Zero all motion, immediately | never gated |
Safety
robotd on the robot holds the only write handle to the motor bus and enforces
joint clamps, fall→limp, and an intent deadman. This server adds its own layer
on top — velocity caps, a 15% battery floor for motion, rate limiting — because
an agent-agnostic tool can't assume the calling model is careful. duck_stop
is always available.
Transports
| What | Needs |
| Canned state, instant | nothing |
| Headless CPU MuJoCo running the official |
|
| The robot's own daemons over | running on the duck |
| The same sockets and the console forwarded over | a duck on the network, ssh access |
All four sit behind one DuckTransport interface, so the tools — and the
safety layer — are identical whether the duck is simulated or real.
Sim fidelity note: the reference MuJoCo scene under-tracks small velocity
commands (verified identical to upstream's own infer_policy.py). Expect
~0.08 m/s at the 0.25 m/s cap and weak yaw. It walks, sits, stands, kicks
and rolls; it just isn't a speed benchmark.
Ecosystem
MicroduckHub — DuckHub, the community policy browser this server backs through upstream's policy channel (daemon 0.13+).
awesome-microduck — the curated ecosystem list.
Not an official project
Community project — not affiliated with, endorsed by, or sponsored by Pollen Robotics or Hugging Face. Microduck is their product; this is an independent client for it, and product names and logos belong to their respective owners.
Status
Pre-hardware. Every transport speaks upstream's published wire protocol
(duck-ipc-proto, see src/transport/protocol.ts); the sim path is
validated end to end, the unix/ssh paths against a fake daemon and a fake
mediad console only —
first contact with a real duck is ~Dec 2026.
Licensed under Apache-2.0 (see LICENSE); upstream robot software is Apache 2.0 too.
Available Tools
8 toolsduck_behaviorRun a behaviorA
Trigger a named built-in behavior: sit, stand, getup (power the joints and rise to the home pose after a fall — on hardware a human rights the duck first; in sim it is set upright in place), pickup (beak to floor, grab), kick, roulade (forward roll), quack. sit/stand are no-ops if already in that posture. Scripted moves take 0.5–3 s; call duck_monitor to see when 'busy' clears. Battery- and health-gated like walking (quack is free).
Inputs: name (required).
duck_cameraDuck cameraA
A still frame of what the duck sees or looks like right now, returned as a PNG image. view='head' is the robot's own head camera; 'follow' (default), 'front', 'side' and 'top' are third-person views around the robot. Read-only, never moves the robot. Available on the sim transport today; on hardware it will come from mediad's WebRTC stream (not wired yet) and the mock transport returns a placeholder.
Inputs: view, width, height.
duck_healthDuck healthA
Full hardware+software health report: battery (volts and percent), control-loop rate, servo/board temperatures, loaded policy, and whether the robot considers itself healthy. Read-only and always safe to call. Call this FIRST in any session, and again before any sequence of motion commands.
Inputs: no named parameters.
duck_monitorDuck state sampleA
One robot.state frame: which policy is driving, the velocity requested vs applied (and what limited it), joints, gravity in the body frame (≈[0,0,-1] when upright — a large X or Y component means it has fallen), odometry, and the safety flags (fallen, limp, busy). Read-only and always safe to call. Use it to confirm a walk actually moved the robot, or to check posture before/after a behavior. For battery and temps use duck_health.
Inputs: no named parameters.
duck_stopSTOP the duckA
Immediately zero all motion intents. NEVER gated, never rate-limited — always available. Call this if anything looks wrong, if a human asks you to stop, or if you are unsure what the robot is doing.
Inputs: no named parameters.
duck_updatesList installed releasesA
Installed daemon releases and which one is active/golden. Read-only. (Installing/rolling back is deliberately NOT exposed as a tool yet — see CLAUDE.md 'Deliberately excluded'.)
Inputs: no named parameters.
duck_versionDuck identity and uptimeA
The robot's name, serial and uptime (configd system.info). Read-only.
Inputs: no named parameters.
duck_walkWalk the duckA
Send a velocity intent: vx forward m/s, vy sideways m/s, wz yaw rad/s. Values are clamped to ±0.25 m/s linear and ±1 rad/s yaw. Walks for duration_s (default 2 s, max 10 s) then stops; the call returns when the walk is over. duck_stop interrupts it at any time, and robotd's own deadman stops the duck if this server dies mid-walk — it does not run away. Call duck_monitor afterwards to see how far it got. Refused below 15% battery or when fallen.
Inputs: vx (required), vy, wz, duration_s.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The status tools (version, health, updates, monitor) overlap somewhat in being read-only system queries, but their descriptions clearly partition them into identity, health, software releases, and live robot state. Motion tools (stop, walk, behavior) and camera are unambiguous.
All tools share a consistent duck_ prefix and the names are short, readable, and predictable. The mix of noun-like names (duck_camera, duck_health) and imperative verbs (duck_stop, duck_walk) is a minor deviation rather than a chaotic convention.
Eight tools is well-scoped for a robot observation and control server: four read-only status/observation tools, three motion/behavior tools, and one emergency stop. Each tool has a clear purpose and none feel redundant.
The tool set covers the full intended workflow: inspect health and state, get a visual feed, command locomotion and behaviors, and stop in an emergency. The deliberate exclusion of update installation/rollback is documented and does not leave an operational gap for normal robot use.
Maintenance
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Connect any AI agent to 1,000+ apps and 27,000+ actions through one remote MCP server (OAuth).
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
214 tools for AI agents over one MCP endpoint: image, video, audio, 3D, data, storage, mail, GPUs.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI models to monitor and control Kachaka robots via MCP, including navigation, shelf operations, and sensor data access.1Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI systems to control the Reachy Mini robot—speak, listen, see, and express emotions through physical movement. Compatible with Claude, GPT, Grok, and other MCP-compatible AIs.MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLM agents to control and monitor a Unitree Go2 robot through MCP tools, including live telemetry, navigation, camera feeds, and waypoint missions.Apache 2.0
- AlicenseAqualityCmaintenanceEnables AI agents to control a simulated Pollen Robotics Microduck through MCP tools for movement, tricks, pushing, camera views, and state inspection.83Apache 2.0