Integrating with Claude

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

The reachy-mini-mcp project enables AI systems like Claude to control a Pollen Robotics' Reachy Mini robot. It acts as a server implementing the Model-Context-Protocol (MCP), exposing a set of tools that an AI can call to interact with the physical world through the robot's hardware. This allows Claude to see, speak, listen, and express emotions via physical movement.

This integration is designed to be token-efficient and requires no prior robotics expertise. The server abstracts the complexities of robot control into a simple, tool-based API.

Sources: README.md:3-7, src/server.py:3-6

System Architecture

The integration follows a layered architecture where Claude communicates with the MCP server, which in turn translates tool calls into commands for the robot's SDK and underlying daemon. This daemon then controls either the physical robot or a MuJoCo-based simulator.

Sources: README.md:41-43

The data flow from the AI to the robot is as follows:

Configuration

To enable Claude to use the reachy-mini-mcp server, you must configure your Claude client to recognize and launch it. The configuration specifies the command to start the server and any necessary environment variables.

Sources: README.md:71-73

Claude Desktop App

For the Claude desktop application, create or modify the configuration file at ~/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"
      }
    }
  }
}

Sources: README.md:75-86

Claude Code (CLI)

For command-line usage with Claude, the configuration file is ~/.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:88-99

Configuration Parameters

The mcpServers object contains the necessary details for Claude to manage the server process.

Parameter	Description
command	The executable to run. poetry is used to manage the project's environment.
args	A list of arguments passed to the command. This specifies the path to the project and the Python script to execute (src/server.py).
env	An object of environment variables to set for the server process, such as API keys.

Sources: README.md:77-83, README.md:91-97

MCP Tool Interface

Claude interacts with the robot by calling a set of 7 tools defined in the MCP server. These tools are exposed via the FastMCP library and are designed to be simple and memorable, following Miller's Law.

Sources: README.md:11, src/server.py:8, src/server.py:27-44

Tool Summary

The following tools are available for programmatic use by an AI like Claude.

Tool	Args	Purpose
speak	text, listen_after=0	Voice + gesture, optionally listen after
listen	duration=3	Speech-to-text via Deepgram Nova-2
snap	-	Camera capture (base64 JPEG)
show	emotion, move=""	Express emotion or play recorded move
look	roll, pitch, yaw, z, duration	Head positioning (degrees)
rest	mode="neutral"	Set robot to neutral, sleep, or wake state
discover	library="emotions"	Find available recorded moves

Sources: README.md:14-25, src/server.py

Interaction Flow

When Claude decides to use a tool, it sends a tool call request to the MCP server. The server executes the corresponding Python function and returns a result.

The following diagram illustrates the sequence for a speak tool call.

Sources: src/server.py:614-690, src/server.py:693-736

Environment Variables

The MCP server's behavior, particularly for voice services, is controlled by environment variables. These must be provided in the Claude configuration file's env block.

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).
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.

*Required if XAI_API_KEY is not set.

Sources: README.md:101-108

Conclusion

The reachy-mini-mcp project provides a robust and straightforward bridge for integrating Claude with the Reachy Mini robot. By defining a simple server configuration and leveraging a concise set of MCP tools, developers can empower Claude with physical embodiment, enabling a new class of interactive and expressive AI applications. The architecture effectively abstracts robotics complexity, allowing the focus to remain on the AI's behavior and interaction design.

Sources: README.md:3-7, src/init.py:1