Project Dependencies
Relevant source files
The following files were used as context for generating this wiki page:This project, reachy-mini-mcp, relies on a combination of Python packages, external web services, and a local daemon to function. The dependencies enable the MCP server to provide a high-level tool interface for controlling the Reachy Mini robot, including capabilities for speech, listening, vision, and movement. The project is licensed under the MIT License.
The dependency architecture can be visualized as a stack, where the MCP server utilizes Python libraries to communicate with both cloud-based APIs and a local robot control daemon. This structure abstracts the complexities of robotics and voice services into a simple set of tools for an AI system.
Sources: README.md:3-7, src/init.py:1, LICENSE
Dependency Architecture Overview
The following diagram illustrates the high-level relationship between the reachy-mini-mcp server, its direct Python dependencies, the external services it consumes, and the underlying robot hardware or simulator.
This diagram shows the flow from an AI system making a tool call to the MCP server, which then uses its Python dependencies to interact with external services and the robot daemon.
Sources: README.md:43, pyproject.toml:11-15, src/server.py:441-448, 483-490
Python Package Dependencies
The project's core Python dependencies are managed by Poetry and defined in pyproject.toml. These packages provide the foundational libraries for the MCP server, robot interaction, and API communication.
Sources: pyproject.toml:10-15, README.md:33-36
| Package | Version | Purpose |
|---|---|---|
python | ^3.10 | The required Python interpreter version. |
fastmcp | ^2.0.0 | The framework used to create and run the MCP server, defining the tools available to the AI. |
reachy-mini | git | The official SDK from Pollen Robotics for controlling the Reachy Mini robot. It is installed from the develop branch of its GitHub repository with the mujoco extra for simulation support. |
openai | ^1.50.0 | Used as a client to interact with the Grok Voice API, which provides an OpenAI-compatible endpoint. |
websockets | ^13.0 | A library for building WebSocket clients and servers, likely a dependency for fastmcp or other asynchronous communication. |
Sources: pyproject.toml:11-15, README.md:104-105
reachy-mini SDK
This is the most critical dependency for robot control. The MCP server uses it to connect to the robot (or simulator) via a lazy-initialized singleton pattern. The connection is established on the first tool call that requires robot interaction.
# src/server.py:183-189
def get_robot():
"""
Get or create robot connection.
Uses lazy initialization - connects on first tool call.
Uses no_media backend for headless simulation compatibility.
"""
global _robot_instance
if _robot_instance is None:
The SDK is installed directly from a git repository, ensuring the project uses a specific development version.
# pyproject.toml:13
reachy-mini = {git = "https://github.com/pollen-robotics/reachy_mini.git%22%2C branch = "develop", extras = ["mujoco"]}
Sources: pyproject.toml:13, src/server.py:183-204
External Service Dependencies
The server relies on several external and local network services, which are configured primarily through environment variables.
Sources: README.md:88-95
Voice & Speech Services
The speak and listen tools depend on third-party APIs for Text-to-Speech (TTS) and Speech-to-Text (STT). The system prioritizes Grok Voice for TTS if configured, otherwise falling back to Deepgram. Deepgram is always used for STT.
| Service | Purpose | Configuration |
|---|---|---|
| Grok Voice | Preferred TTS for expressive voice synthesis. | XAI_API_KEY environment variable. |
| Deepgram | Fallback TTS (Aura 2) and primary STT (Nova 2). | DEEPGRAM_API_KEY environment variable. |
Sources: README.md:58-65, 88-95, src/server.py:441-448, 571-578
TTS Provider Selection Logic
The text_to_speech function checks for the XAI_API_KEY to decide which service to use.
This diagram shows the conditional logic for choosing a TTS provider.
Sources: src/server.py:441-448
Grok Voice API Interaction
The openai Python library is configured with a custom base_url to communicate with the x.ai API for Grok Voice.
# src/server.py:503-506
client = AsyncOpenAI(
api_key=api_key,
base_url="https://api.x.ai/v1"
)
Sources: src/server.py:503-506
Reachy Mini Daemon
All direct robot control commands from the reachy-mini SDK are sent to the Reachy Mini Daemon, which must be running locally. The MCP server communicates with this daemon to execute movements, play recorded moves, and manage the robot's state.
- Default URL:
http://localhost:8321/api - Configuration:
REACHY_DAEMON_URLenvironment variable.
The discover and show(move=...) tools interact directly with the daemon's HTTP API to list and play pre-recorded moves from HuggingFace libraries.
This sequence shows how the discover and show tools rely on the daemon's API endpoints.
Sources: README.md:43, 94, src/server.py:816-820, 843-851
System and Hardware Requirements
Beyond Python packages, running the project has further system-level requirements.
- Python: Version 3.10 or newer.
- MuJoCo: Required for running the robot in simulation mode. The
README.mdnotes thatmjpythonis needed on macOS for visualization. - Hardware: To control a physical robot, the Reachy Mini hardware is required. The same MCP server code works for both the simulator and the real hardware.
Sources: pyproject.toml:11, README.md:104-108