Troubleshooting Guide

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 solutions for common issues encountered when setting up and running the Reachy Mini MCP server. It covers connection problems, tool execution failures, and configuration errors, based on the system's architecture and error handling logic. The server acts as a bridge between an AI system (like Claude or GPT) and the Reachy Mini robot, enabling control through a set of defined tools.

The overall system architecture involves the AI calling tools on the MCP Server, which in turn uses the Reachy Mini SDK to communicate with a daemon process that controls the physical robot or a simulator. Understanding this flow is key to diagnosing problems.

Sources: README.md:3-10, src/server.py:3-8

System Architecture Flow

This diagram illustrates the data flow from the AI to the robot. Issues can arise at any connection point.

1. Connection and Startup Issues

Problems often occur during the initial connection between the MCP server and the Reachy Mini daemon. The server uses lazy initialization, meaning the connection is only attempted on the first tool call.

Sources: src/server.py:186-189

1.1. Cannot Connect to Reachy Mini Daemon

If you receive an error like "Could not connect to Reachy Mini. Is the daemon running?", it indicates the MCP server failed to establish a connection with the robot's control daemon.

Troubleshooting Steps:

1. Verify Daemon is Running: The Reachy Mini daemon must be active. For the simulator, start it with:

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

2. Check Daemon URL: The server defaults to http://localhost:8321/api. If your daemon is on a different host or port, set the REACHY_DAEMON_URL environment variable.
3. Check for Port Conflicts: The daemon uses port 8321 by default. Ensure no other application is using this port. The underlying Zenoh communication protocol uses port 7447.

This flowchart shows the connection logic within the get_robot() function.

1.2. SDK Not Installed

An error message RuntimeError: reachy-mini SDK not installed indicates a missing dependency.

Solution:
Install the project dependencies using Poetry. This will fetch the reachy-mini SDK from the specified git repository.

poetry install

Sources: pyproject.toml:11-12, src/server.py:198-200

2. Tool Execution Failures

Failures can occur within specific tools, often due to missing API keys, incorrect arguments, or issues with downstream services.

2.1. speak or listen Tool Fails

These tools rely on external voice services (Grok Voice or Deepgram).

Error Cause	Solution
DEEPGRAM_API_KEY environment variable not set	Set the DEEPGRAM_API_KEY environment variable. This is required for listen and as a fallback for speak.
Grok error: ...	An issue occurred with the x.AI API. Check your XAI_API_KEY and the Grok service status.
Heard: (silence or unclear audio)	The microphone may not have picked up clear audio. Check microphone hardware and environment noise. The _do_listen function returns an empty string if the transcript is empty.

Sources: README.md:34-37, README.md:83-87, src/server.py:440-443, src/server.py:560-562, src/server.py:821-823

Text-to-Speech Provider Selection

The speak tool uses the text_to_speech helper, which has a specific provider selection logic. This diagram shows how it chooses between Grok Voice and Deepgram.

2.2. show(move=...) or discover Fails

These tools communicate directly with the Reachy Mini daemon's HTTP API to manage recorded moves from HuggingFace libraries.

Common Errors:

• Cannot connect to daemon. Is it running on localhost:8321?: This is a httpx.ConnectError. The troubleshooting steps are the same as in section 1.1. Cannot Connect to Reachy Mini Daemon.
• Move '...' not found in ...: The specified move name does not exist in the selected library. Use discover() to see a list of valid move names.
• Failed to list moves: ...: A generic error occurred while trying to fetch the move list from the daemon. Check the daemon's logs for more details.

The following sequence diagram shows the interaction for discovering moves.

2.3. snap Tool Fails

The snap tool captures an image from the robot's camera.

Error Cause	Solution
OpenCV not available for image encoding	The cv2 library (OpenCV) is not installed correctly. It is included as part of the reachy-mini[mujoco] extras. A poetry install should resolve this.
No frame captured	The camera returned None. This could be a hardware issue, a problem with the media backend configuration (REACHY_MEDIA_BACKEND), or an issue in the daemon.

Sources: pyproject.toml:12, src/server.py:849-864

3. Configuration

Incorrect configuration is a frequent source of problems.

3.1. Environment Variables

The server relies on several environment variables for its operation.

Variable	Required	Default	Purpose & Troubleshooting
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. Must be one of Ara, Eve, Leo, Rex, Sal, Mika, Valentin.
DEEPGRAM_API_KEY	Yes*	-	API key for Deepgram. Required for listen and for speak if XAI_API_KEY is not set.
REACHY_DAEMON_URL	No	http://localhost:8321/api	URL for the Reachy daemon. Change if the daemon is not running on the default localhost port.
REACHY_MEDIA_BACKEND	No	default_no_video	Configures the SDK's media handling. default_no_video is compatible with the simulator. no_media for headless. default for real hardware.

*Required if XAI_API_KEY not set.

Sources: README.md:83-88, src/server.py:194-195

3.2. Claude MCP Configuration

For integration with Claude, the MCP server must be correctly registered in the Claude configuration file. An incorrect path in the args can prevent the server from starting.

Example for Claude Desktop:
File: ~/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"
      }
    }
  }
}

Ensure /path/to/reachy-mini-mcp is the correct absolute path to the repository on your machine.

Sources: README.md:61-71

4. Graceful Shutdown

The server registers a cleanup function to be called on exit. This function, cleanup_robot, ensures that the connection to the robot is properly closed. If the server process is terminated abruptly (e.g., with kill -9), this cleanup may not run, potentially leaving the robot in an unstable state. It's recommended to stop the server with Ctrl+C to allow for graceful shutdown.

Sources: src/server.py:207-217, src/server.py:973-975