Reachy Mini

You can control Reachy Mini robots through an MCP (Model Context Protocol) server, enabling natural language interactions via clients like Claude Desktop. This server exposes commands to make the robot dance, express emotions, move its head, capture camera images, track faces, speak locally, and manage motion status—all while running entirely on your machine once installed.

How to use

You interact with the Reachy Mini MCP server by connecting an MCP client and issuing high‑level actions. Use choreographies to run dances, trigger pre‑recorded emotions, and adjust where the robot looks. Turn on and off head tracking, capture camera images when enabled, and listen to the robot speak with on‑device, real‑time text‑to‑speech. You can stop all motions immediately and query the current status to monitor the robot’s state and pose.

How to install

Prerequisites: you need Python 3.10 or newer and a working Python environment. You will also rely on the Reachy Mini SDK and a running Reachy Mini daemon or simulation.

# Clone the project
git clone https://github.com/pixelml/reachy-mini-mcp.git
cd reachy-mini-mcp

# Create a Python virtual environment (Python 3.10)
uv venv --python 3.10
source .venv/bin/activate

# Install library dependencies
uv pip install -e .

# Optional: add camera support
uv pip install -e ".[camera]"

# Optional: add speech support for on-device TTS
uv pip install -e ".[speech]"

Configuration and runtime notes

Configure environment variables to tailor the server to your robot and hardware setup. The following options are available and commonly used:

• REACHY_MINI_ROBOT_NAME: sets the robot name for discovery and identification (default: reachy-mini). Use a name that matches your robot or your Zenoh network configuration.

• REACHY_MINI_ENABLE_CAMERA: enables camera capture; set to true to enable image capture features.

• REACHY_MINI_HEAD_TRACKING_ENABLED: Start with head tracking enabled; set to true to have head tracking active on startup.

Claude Code CLI and Claude Desktop integration

To add the MCP server to Claude Code CLI, you build from source and register the server with stdio transport. You can also enable camera support and customize the robot name via environment variables.

Available tools and actions (endpoints)

You can access the following actions through the MCP server:

• simple_nod

• head_tilt_roll

• side_to_side_sway

• dizzy_spin

• stumble_and_recover

• interwoven_spirals

• sharp_side_tilt

• side_peekaboo

• yeah_nod

• uh_huh_tilt

• neck_recoil

• chin_lead

• groovy_sway_and_roll

• chicken_peck

• side_glance_flick

• polyrhythm_combo

• grid_snap

• pendulum_swing

• jackson_square

• left

• right

• up

• down

• front

• alba

• marius

• javert

• jean

• fantine

• cosette

• eponine

• azelma

Running the server directly

You can start the MCP server directly from the command line using the reachy-mini-mcp executable.

reachy-mini-mcp

Available tools

dance

Play a dance move on the robot. Parameters: move (string, optional): dance name or 'random'; repeat (integer, optional): number of repeats.

play_emotion

Play a pre-recorded emotion. Parameter: emotion (string, required).

move_head

Move the robot’s head in a direction. Parameters: direction (string, required): one of 'left','right','up','down','front'; duration (float, optional): movement duration in seconds.

camera

Capture an image from the robot’s camera. Returns: Base64-encoded JPEG. Requires camera to be enabled.

head_tracking

Toggle head tracking mode. Parameter: enabled (boolean, required).

stop_motion

Stop all current and queued motions immediately.

speak

Speak using real-time local TTS with natural head movement. Parameters: text (string, required); voice (string, optional). Available voices: alba, marius, javert, jean, fantine, cosette, eponine, azelma.

get_status

Get current robot status including connection state, queue size, and current pose.