Environment Variables

Relevant source files

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

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

Environment variables are the primary method for configuring the reachy-mini-mcp server. They control critical settings such as API keys for third-party services, connection details for the robot daemon, and behavior of specific tools like voice synthesis and robot initialization. Correctly setting these variables is essential for the server to function, particularly for features involving speech and listening.

The server reads these variables at runtime to dynamically configure its dependencies and select appropriate service providers. For example, the presence of an XAI_API_KEY will automatically prioritize Grok Voice for text-to-speech (TTS) over the Deepgram fallback.

Sources: README.md, src/server.py

Configuration Summary

The following table summarizes all environment variables used by the application, their purpose, and default values.

Variable	Required	Default Value	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.
DEEPGRAM_API_KEY	Yes*	-	API key for Deepgram. Used for TTS (as a fallback if XAI_API_KEY is not set) and always for Speech-to-Text (STT).
REACHY_DAEMON_URL	No	http://localhost:8321/api	The API endpoint for the Reachy Mini daemon, which controls the physical robot or simulator.
REACHY_MEDIA_BACKEND	No	default_no_video	Configures the media backend for the reachy-mini SDK, controlling audio and camera access.

*DEEPGRAM_API_KEY is required if XAI_API_KEY is not set for speech, and is always required for the listen() tool.

Sources: README.md:104-109, src/server.py:195, src/server.py:444, src/server.py:588

Detailed Variable Usage

Voice Service Configuration

The server can use two different Text-to-Speech (TTS) providers: Grok Voice (preferred) and Deepgram Aura (fallback). The selection is determined by the presence of the XAI_API_KEY environment variable.

The diagram below illustrates the logic within the text_to_speech function for selecting a TTS provider.

XAI_API_KEY

This variable holds the API key for xAI's services. When set, the text_to_speech function will call grok_text_to_speech to generate audio.

Sources: src/server.py:409

GROK_VOICE

This variable customizes the voice used by Grok Voice. The selection logic prioritizes the voice parameter in the speak() tool, then this environment variable, and finally defaults to "eve".

# src/server.py:453-456
# Voice priority: parameter > env var > default
if voice and voice.lower() in GROK_VOICES:
    voice = voice.lower()
else:
    voice = os.environ.get("GROK_VOICE", "eve").lower()

Sources: README.md:106, src/server.py:456

DEEPGRAM_API_KEY

This key is mandatory for two functions:

1. Speech-to-Text (STT): The listen() tool and the listen_after parameter in speak() rely exclusively on Deepgram's Nova-2 model. If this key is missing, any attempt to transcribe audio will fail.
2. Fallback TTS: If XAI_API_KEY is not provided, the speak() tool falls back to using Deepgram's Aura-2 model for TTS.

The following sequence diagram shows how DEEPGRAM_API_KEY is used for STT.

Sources: README.md:107, src/server.py:417-419, src/server.py:539-541

Robot Connection Configuration

REACHY_DAEMON_URL

This variable specifies the full URL to the Reachy Mini daemon's API. It is used for interacting with recorded moves, such as listing them with discover() or playing them with show(move=...). The default value points to a local daemon instance.

# src/server.py:588
DAEMON_URL = os.environ.get("REACHY_DAEMON_URL", "http://localhost:8321/api")

This URL is then used to construct API calls to endpoints like /move/running and /move/play/recorded-move-dataset/....

Sources: README.md:108, src/server.py:588, src/server.py:599, src/server.py:644

REACHY_MEDIA_BACKEND

This variable is used during the lazy initialization of the robot connection in the get_robot() function. It determines which media backend the reachy-mini SDK should use, controlling access to the robot's camera and microphones. The default value default_no_video is chosen for simulator compatibility.

# src/server.py:194-195
# Use 'no_media' for headless (no audio or camera)
backend = os.environ.get("REACHY_MEDIA_BACKEND", "default_no_video")
_robot_instance = ReachyMini(media_backend=backend)

Sources: src/server.py:195-196

Setting Variables for Claude

The README.md provides examples of how to configure the MCP server for use with Claude applications. The environment variables are passed via an env dictionary within the JSON configuration file.

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"
      }
    }
  }
}

Claude Code (~/.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"
      }
    }
  }
}

In these examples, DEEPGRAM_API_KEY is set, but other variables like XAI_API_KEY could be added to the env object as needed.

Sources: README.md:80-92, README.md:95-101