API Key Management

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

The reachy-mini-mcp server integrates with third-party services for voice capabilities, specifically Text-to-Speech (TTS) and Speech-to-Text (STT). Access to these services is managed through API keys configured via environment variables. This system allows for flexible selection of voice providers and secure handling of credentials without hardcoding them into the source.

The primary services requiring API keys are Grok Voice for preferred TTS and Deepgram for fallback TTS and all STT functionalities. Proper configuration of these keys is essential for the speak() and listen() tools to function correctly.

Sources: README.md, src/server.py

Supported Services and Keys

The server utilizes two main external services for its voice features, each requiring a specific API key set as an environment variable.

Service	Environment Variable	Purpose	Required
Grok Voice	XAI_API_KEY	Preferred Text-to-Speech (TTS)	No
Deepgram	DEEPGRAM_API_KEY	Fallback TTS and all Speech-to-Text (STT)	Yes*

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

Sources: README.md:88-93, src/server.py:423-427, 533-537

Configuration Methods

API keys are provided to the application exclusively through environment variables. This can be done directly in the shell or through a configuration file for integrated environments like Claude.

Shell Export

For local development or direct execution, keys can be exported in the shell session before running the server.

# Set API key (required for speak/listen)
export DEEPGRAM_API_KEY=your_key_here
export XAI_API_KEY=your_grok_key_here # Optional

# Run MCP server
poetry run python src/server.py

Sources: README.md:52-55

Claude Integration

When running the server via Claude Desktop or Claude Code, the environment variables are set within the respective JSON configuration file. This ensures the MCP server process starts with the necessary credentials.

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",
        "XAI_API_KEY": "your_grok_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"
      }
    }
  }
}

Sources: README.md:99-113, README.md:115-126

API Key Usage and Logic

The server's Python code reads the environment variables at runtime to authenticate with the external voice services.

Text-to-Speech (TTS) Provider Selection

The text_to_speech function implements a fallback mechanism. It prioritizes Grok Voice if XAI_API_KEY is available; otherwise, it defaults to Deepgram.

This diagram illustrates the provider selection logic within the text_to_speech function.

Grok Voice (x.ai) TTS

When XAI_API_KEY is set, the grok_text_to_speech function is called. It uses the openai Python library, configured with Grok's API endpoint, to synthesize speech.

The following sequence diagram shows the process of generating speech with Grok Voice.

Deepgram TTS (Fallback)

If XAI_API_KEY is not present, the server falls back to using Deepgram for TTS. The deepgram_text_to_speech function makes a direct HTTP POST request to the Deepgram API, authenticating with the DEEPGRAM_API_KEY.

This diagram shows the sequence for Deepgram TTS.

Deepgram Speech-to-Text (STT)

For the listen() functionality, the server exclusively uses Deepgram's Nova-2 model. The speech_to_text function is called with the recorded audio data, and it authenticates using the DEEPGRAM_API_KEY.

This diagram shows the sequence for transcribing audio with Deepgram.