The MCP Server
Relevant source files
The following files were used as context for generating this wiki page:The Reachy Mini MCP Server is a Python application that acts as a bridge between AI systems (like Claude, GPT, or Grok) and Pollen Robotics' Reachy Mini robot. It exposes the robot's capabilities—speaking, listening, seeing, and expressing emotions—as a set of simple tools that an AI can call programmatically. This allows an AI to be given a physical body, enabling "embodied consciousness expression." The server is built using the FastMCP library, which implements the Model-Context Protocol (MCP).
The server provides seven core tools designed to be token-efficient and easy for an AI to use, following Miller's Law of keeping the set of options within working memory. These tools abstract away the complexities of robotics control, allowing the AI to focus on high-level actions like expressing joy or looking at an object, rather than low-level motor commands. The project is licensed under the MIT License.
Sources: src/server.py:1-29, README.md:3-7, src/init.py:1, LICENSE
Architecture
The MCP server is a middleware component that sits between the AI model and the robot's control daemon. The end-to-end control flow follows a clear path from the AI's tool call to the physical or simulated robot's movement.
Sources: README.md:41-45
The following diagram illustrates the data flow from the AI to the robot.
This diagram shows the architectural flow from AI tool call to robot action.
Sources: README.md:41-45, src/server.py:5-7
Configuration
The server is configured primarily through environment variables. These are used to set API keys for voice services and to specify the location of the robot's control daemon.
Sources: README.md:85-92
Environment Variables
| Variable | Required | Default | Purpose |
|---|---|---|---|
XAI_API_KEY | No | - | API key for Grok Voice TTS (preferred). |
GROK_VOICE | No | Eve | Specifies the Grok voice to use (e.g., Ara, Eve, Leo, Rex, Sal). |
DEEPGRAM_API_KEY | Yes* | - | API key for Deepgram TTS (fallback) and STT. |
REACHY_DAEMON_URL | No | http://localhost:8321/api | The API endpoint for the Reachy Mini daemon. |
REACHY_MEDIA_BACKEND | No | default_no_video | Configures the media backend for the SDK (no_media for headless). |
Required if XAI_API_KEY is not set.
Sources: README.md:85-92, src/server.py:186-187, src/server.py:1001-1001
Claude Integration
The server can be integrated with Claude clients by adding its configuration to the respective JSON files. This allows Claude to discover and use the reachy-mini MCP server.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"reachy-mini": {
"command": "poetry",
"args": ["-C", "/path/to/reachy-mini-mcp", "run", "python", "src/server.py"],
"env": {
"DEEPGRAM_API_KEY": "your_key_here"
}
}
}
}
Sources: README.md:65-76
Core Components
MCP Initialization
The server is initialized as a FastMCP instance named reachy-mini. It includes a detailed instruction prompt that guides the AI on how to use the available tools for expressive robotics control.
# src/server.py:32-52
mcp = FastMCP(
name="reachy-mini",
instructions="""
Reachy Mini robot control for expressive robotics.
Use these tools for robot control:
- show() for 12 built-in emotions (curious, joy, thinking, etc.)
- show(move=...) for 81 recorded emotions from Pollen (fear1, rage1, serenity1, etc.)
- discover() to see available recorded moves
- look() for precise head positioning
- speak() to vocalize with [move:X] markers for choreography
- listen() to hear and transcribe speech
- snap() to capture camera images
- rest() for neutral pose, sleep, or wake
Prefer show() for common emotions, show(move=...) for nuanced expressions.
"""
)
Sources: src/server.py:32-52
Robot Connection Management
The connection to the Reachy Mini robot is managed through a lazy-initialized global instance. The get_robot() function establishes the connection on the first tool call, which improves startup time and resource usage. A cleanup function, cleanup_robot(), is registered with atexit to ensure the connection is properly closed on server shutdown.
Sources: src/server.py:177-207
This diagram shows the lazy initialization flow.
This diagram shows the logic of the get_robot() function.
Sources: src/server.py:177-199
MCP Tools
The server exposes 7 tools for robot control.
Sources: README.md:11-20, src/server.py:8-16
show()
This tool is the primary method for making the robot express emotions. It supports two modes: using one of 12 fast, built-in emotions, or playing one of 81 pre-recorded, more nuanced moves from the Pollen Robotics library.
| Parameter | Type | Description |
|---|---|---|
emotion | str | A built-in emotion to express. Defaults to "neutral". |
move | str | A recorded move name to play. Overrides emotion if provided. |
The show() function acts as a dispatcher, calling _do_express() for built-in emotions and _do_play_move() for recorded moves.
This diagram shows the control flow within the show() tool.
Sources: src/server.py:302-337, README.md:28-36
look()
Provides direct, precise control over the robot's head orientation and vertical position.
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
roll | float | 0 | -45 to 45 | Tilt head left/right. |
pitch | float | 0 | -30 to 30 | Nod head up/down. |
yaw | float | 0 | -90 to 90 | Turn head left/right. |
z | float | 0 | -20 to 20 | Vertical offset. |
duration | float | 1.0 | 0.1 to 5.0 | Movement time in seconds. |
The function clamps input values to safe ranges before creating a head pose matrix and sending it to the robot.
Sources: src/server.py:340-381
speak()
Enables the robot to speak using text-to-speech (TTS) and supports choreographing movements with speech. It can also listen for a response after speaking.
| Parameter | Type | Default | Description |
|---|---|---|---|
text | str | - | The text to speak. Can contain [move:name] markers. |
listen_after | float | 0 | Seconds to listen for a response after speaking. |
voice | str | "eve" | The Grok voice to use if XAI_API_KEY is set. |
The speak function has a sophisticated flow: it parses the text for move markers, triggers the moves, generates audio for text segments, plays the audio, and optionally listens for a reply.
This diagram illustrates the logic for handling simple and choreographed speech.
Sources: src/server.py:614-706, README.md:22-26
listen()
Captures audio from the robot's microphones for a specified duration and transcribes it to text using Deepgram's Nova-2 STT service.
| Parameter | Type | Default | Range | Description |
|---|---|---|---|---|
duration | float | 3.0 | 1 to 30 | How long to listen in seconds. |
The following sequence diagram shows the process of recording and transcribing audio.
This diagram shows the sequence of events for the listen tool.
Sources: src/server.py:788-806, src/server.py:710-766
snap()
Captures a single frame from the robot's camera and returns it as a base64-encoded JPEG image. This is the robot's primary visual perception tool.
Sources: src/server.py:809-832, README.md:15-15
rest()
Controls the robot's power and resting states.
| Parameter | Type | Default | Description |
|---|---|---|---|
mode | str | "neutral" | Can be "neutral", "sleep", or "wake". |
neutral: Returns the robot to a standard, upright pose.sleep: Puts the robot into a low-power state.wake: Wakes the robot from sleep mode.
Sources: src/server.py:835-857
discover()
Lists the available pre-recorded moves from Pollen Robotics' HuggingFace libraries. This allows the AI to learn which moves can be used with show(move=...).
| Parameter | Type | Default | Description |
|---|---|---|---|
library | str | "emotions" | The library to query, either "emotions" or "dances". |
This tool makes an HTTP GET request to the Reachy Daemon to fetch the list of moves.
Sources: src/server.py:1015-1042, README.md:19-19
Voice Services
The server integrates with two third-party voice services for Text-to-Speech (TTS) and Speech-to-Text (STT).
Sources: README.md:47-53
Text-to-Speech (TTS)
The text_to_speech function dynamically chooses a provider. It prioritizes Grok Voice if an XAI_API_KEY is set, otherwise it falls back to Deepgram's Aura-2 model.
This diagram shows the TTS provider selection logic.
- Grok Voice: Used when
XAI_API_KEYis present. It connects to x.ai's realtime API to generate expressive speech. - Deepgram: Used as a fallback. It calls the Deepgram Aura-2 TTS API.
Sources: src/server.py:384-391, src/server.py:422-498, src/server.py:394-419
Speech-to-Text (STT)
All transcription is handled by the speech_to_text function, which sends recorded audio (in WAV format) to the Deepgram Nova-2 API.
Sources: src/server.py:501-529
Dependencies
The project relies on several key Python packages, which are managed by Poetry.
| Package | Version | Purpose |
|---|---|---|
fastmcp | ^2.0.0 | Core library for creating the MCP server. |
reachy-mini | git | The official SDK for controlling the robot. |
openai | ^1.50.0 | Used as a client for the Grok Voice API. |
websockets | ^13.0 | Dependency for fastmcp. |
Sources: pyproject.toml:10-14
Summary
The Reachy Mini MCP Server is a powerful yet simple service that gives AI models control over a physical robot. By abstracting complex robotics into a small set of intuitive tools, it enables developers and researchers to explore embodied AI applications without needing robotics expertise. Its support for choreographed speech, expressive emotion, and sensory input (vision and hearing) makes it a comprehensive platform for creating interactive and engaging robotic personalities.
Sources: src/server.py:1-29, README.md:3-7