Prerequisites and Installation

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• pyproject.toml
• src/server.py
• src/init.py
• LICENSE

This guide provides the necessary steps and requirements to install, configure, and run the reachy-mini-mcp server. The server acts as a bridge, enabling AI systems like Claude, GPT, or Grok to control a Pollen Robotics' Reachy Mini robot. By following this guide, you will set up an environment where an AI can use a simple set of tools to make the robot speak, listen, see, and express emotions.

The project's architecture involves an AI communicating with the MCP Server, which in turn uses the Reachy Mini SDK to send commands to a daemon controlling either a physical robot or a simulator. This setup allows for rapid prototyping and development without requiring deep robotics expertise.

Sources: README.md:3-9, README.md:40-42

System Requirements

Before proceeding with the installation, ensure your system meets the following software and hardware requirements.

Software Requirements

The project is built on Python and relies on several key libraries for its functionality.

Requirement	Version/Details	Purpose	Source
Python	^3.10	Core programming language.	pyproject.toml:10
reachy-mini SDK	git branch develop	Official SDK for controlling the robot.	pyproject.toml:12
fastmcp	^2.0.0	Framework for creating the MCP server.	pyproject.toml:11
openai	^1.50.0	Used for Grok Voice TTS integration.	pyproject.toml:13
websockets	^13.0	Dependency for real-time communication.	pyproject.toml:14
MuJoCo	-	Required for running the robot simulator.	README.md:104
Deepgram API Key	-	Required for Speech-to-Text (STT) and fallback Text-to-Speech (TTS).	README.md:92

Sources: pyproject.toml:9-14, README.md:102-105

Hardware and Environment Notes

• Simulator vs. Hardware: The same MCP server code works for both the physical robot and the simulator. The underlying daemon handles the connection automatically.
• macOS Simulator: On macOS, mjpython is required to run the MuJoCo visualization for the simulator.
• Port Conflicts: Be aware of potential port conflicts. The Reachy Mini daemon uses port 8321 by default, and its underlying Zenoh communication layer uses port 7447.

Sources: README.md:107-111

Installation and Setup

The installation process uses poetry for dependency management. The following diagram and steps outline the process from cloning the repository to having a runnable server.

This diagram shows the user's journey to get the application ready.

Step-by-Step Guide

1. Clone the Repository
   Clone the project from GitHub to your local machine.

2. Install Dependencies
   Navigate into the project directory and use Poetry to install the required packages. This command reads the pyproject.toml file to install all necessary dependencies, including the reachy-mini SDK with MuJoCo extras.

   cd reachy-mini-mcp
   poetry install
   

   Sources: README.md:32-33, pyproject.toml:12

Configuration

The server's behavior, particularly for voice services, is controlled via environment variables. It can also be configured to integrate directly with AI clients like Claude.

Environment Variables

These variables must be set in your shell or via a configuration file before running the server.

Variable	Required	Default	Purpose
XAI_API_KEY	No	-	API key for Grok Voice TTS. If set, this is the preferred TTS provider.
GROK_VOICE	No	Eve	Specifies the Grok voice to use. Options: Ara, Eve, Leo, Rex, Sal, Mika, Valentin.
DEEPGRAM_API_KEY	Yes*	-	API key for Deepgram. Used for all STT and as a fallback TTS provider.
REACHY_DAEMON_URL	No	http://localhost:8321/api	The API endpoint for the Reachy Mini daemon.

*DEEPGRAM_API_KEY is required if XAI_API_KEY is not set.

Sources: README.md:89-95, src/server.py:461-462

Voice Provider Configuration

The server dynamically selects the Text-to-Speech (TTS) provider based on the available environment variables.

This diagram illustrates the logic for selecting a TTS provider.

The text_to_speech function checks for XAI_API_KEY first. If present, it calls grok_text_to_speech. Otherwise, it falls back to deepgram_text_to_speech, which requires DEEPGRAM_API_KEY. All Speech-to-Text (STT) operations exclusively use Deepgram.

Sources: src/server.py:416-421, src/server.py:530-532

Claude Integration

To integrate with the Claude desktop app or code editor, you need to update its configuration file to point to the reachy-mini-mcp server.

Claude Desktop Configuration
Update ~/Library/Application Support/Claude/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"
      }
    }
  }
}

Claude Code Configuration
Update ~/.claude.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-87

Running the Application

With the prerequisites and configuration complete, you can start the required services.

System Architecture

The overall system architecture follows a clear path from the AI to the robot.

This diagram shows the flow of commands from the AI system to the robot.

Startup Sequence

Two separate processes must be started in order.

This sequence diagram shows the steps to start the simulator and the MCP server.

1. Start the Simulator Daemon
   In a terminal, run the following command to start the Reachy Mini daemon connected to a minimal simulator scene.

   mjpython -m reachy_mini.daemon.app.main --sim --scene minimal
   

   Sources: README.md:36

2. Run the MCP Server
   In a second terminal, set your API key and run the server using poetry.

   export DEEPGRAM_API_KEY=your_key_here
   poetry run python src/server.py
   

   The server is also defined as a script in pyproject.toml, allowing it to be run with poetry run reachy-mini-mcp.

   Sources: README.md:35-39, pyproject.toml:16-17

Server Initialization

The main function in src/server.py starts the FastMCP server. It also registers a cleanup_robot function to ensure the connection to the robot is properly closed on shutdown. The actual connection to the robot is handled lazily by the get_robot function, which only establishes a connection on the first tool call.

Sources: src/server.py:821-826, src/server.py:168-171

Conclusion

By completing these steps, you have successfully installed and configured the reachy-mini-mcp server. The system is now ready to accept tool calls from a compatible AI, translating high-level commands into physical actions, speech, and expressions for the Reachy Mini robot. This setup provides a powerful platform for developing and experimenting with embodied AI.