fr3kr3achy - MCP Server for Reachy Mini Robot Control

Give your AI a body. This MCP server enables AI systems (Claude, Gemini, GPT, etc.) to control the Pollen Robotics Reachy Mini robot through speech, movement, and emotional expression.

Features

• 7 MCP Tools: Complete robot control with token-efficient tool names
• Pluggable TTS: Deepgram, OpenAI, ElevenLabs, or local (Piper/Coqui)
• Dual Transport: stdio (CLI clients) or HTTP (remote deployment)
• Safe Movement: Built-in joint limits and safety clamping
• Expression System: 12 built-in emotions + support for recorded moves
• Camera Integration: Base64 image capture from robot camera
• Zero Robotics Expertise: Works with simulator or real hardware

Quick Start

Installation

# Install globally
npm install -g fr3kr3achy

# Or use with npx (no installation needed)
npx fr3kr3achy

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Configure your environment variables:

# Required for TTS
export DEEPGRAM_API_KEY=your_key_here
# or
export OPENAI_API_KEY=your_key_here

# Optional: Reachy daemon URL (default: http://localhost:8000)
export REACHY_API_URL=http://localhost:8000

Start the Server

stdio mode (for Claude Code, OpenCode, Gemini CLI):

npx fr3kr3achy

HTTP mode (for remote deployment):

npx fr3kr3achy --http:3000

MCP Tools

| Tool | Description | Parameters | |------|-------------|------------| | get_robot_state | Get robot health and joint state | includeJointState? | | move_head | Move head to specific angles | pitch, roll, yaw, speed? | | set_expression | Set facial expression or play move | emotion, intensity?, duration? | | stop_all_movements | Stop movements and set pose | mode? | | get_camera_image | Capture camera image | format?, quality? | | get_antennas_state | Get antenna angles and status | - | | tts_speak | Text-to-speech output | text, provider? | | speak_and_express | Speak while expressing emotion | text, emotion, intensity?, provider? |

Built-in Emotions

• neutral, curious, uncertain, recognition, joy
• thinking, listening, agreeing, disagreeing, sleepy
• surprised, focused

Or use any recorded move name from the Reachy Mini library.

Claude Code Integration

Add to ~/.claude.json:

{
  "mcpServers": {
    "fr3kr3achy": {
      "command": "npx",
      "args": ["fr3kr3achy"],
      "env": {
        "DEEPGRAM_API_KEY": "your_key_here",
        "REACHY_API_URL": "http://localhost:8000"
      }
    }
  }
}

Gemini CLI Integration

Configure in your Gemini CLI config:

mcpServers.fr3kr3achy=http://localhost:3000

Vercel Deployment

Deploy to Vercel for remote access:

vercel add fr3kr3achy
cd fr3kr3achy
vercel --prod

Your MCP endpoint will be available at: https://your-app.vercel.app/mcp

Configuration File

Create fr3kr3achy.config.json:

{
  "reachy": {
    "apiUrl": "http://localhost:8000"
  },
  "tts": {
    "provider": "deepgram",
    "deepgram": {
      "apiKey": "your_key",
      "voice": "aura-neutral-en"
    }
  },
  "server": {
    "httpPort": 3000,
    "logLevel": "info"
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | REACHY_API_URL | No | http://localhost:8000 | Reachy daemon endpoint | | TTS_PROVIDER | No | local | TTS provider to use | | DEEPGRAM_API_KEY | No* | - | Deepgram API key | | OPENAI_API_KEY | No* | - | OpenAI API key | | ELEVENLABS_API_KEY | No* | - | ElevenLabs API key | | LOCAL_TTS_COMMAND | No | - | Local TTS command | | HTTP_PORT | No | 3000 | HTTP server port |

*Required if that provider is selected

Example Usage

Basic Movement

// Look curious
await move_head({ pitch: 10, roll: 5, yaw: 15, speed: 0.7 })

// Show joy
await set_expression({ emotion: 'joy', intensity: 1.0, duration: 3.0 })

Speech with Expression

// Speak while looking happy
await speak_and_express({
  text: "Hello! It's great to see you!",
  emotion: 'joy',
  expressionIntensity: 0.8,
  provider: 'deepgram'
})

Camera Capture

// Get image from robot camera
const image = await get_camera_image({ format: 'jpeg', quality: 90 })
// Returns base64 encoded image

Safety

All joint movements are automatically clamped to safe ranges:

• Pitch: -30° to 30°
• Roll: -20° to 20°
• Yaw: -60° to 60°

Emergency stop: Use stop_all_movements({ mode: 'emergency' })

Development

# Clone repository
git clone https://github.com/your-org/fr3kr3achy
cd fr3kr3achy

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run tests
npm test

Troubleshooting

Connection Issues

Problem: "Cannot connect to Reachy daemon"

Solutions:

1. Ensure Reachy daemon is running: curl http://localhost:8000/api/state/full
2. Check firewall settings
3. Verify REACHY_API_URL is correct

TTS Not Working

Problem: "API key not configured"

Solutions:

1. Set appropriate API key in environment
2. Verify TTS_PROVIDER matches available credentials
3. For local TTS, ensure piper or coqui is installed

MCP Client Not Seeing Tools

Problem: "No tools available"

Solutions:

1. Check server is running in correct mode (stdio vs HTTP)
2. Verify client configuration matches server mode
3. Check logs: server.logLevel = 'debug' in config

License

MIT License - see LICENSE file

Acknowledgments

• Reachy Mini SDK by Pollen Robotics (Apache 2.0)
• MCP SDK by Anthropic
• Inspired by jackccrawford/reachy-mini-mcp

Links

• MCP Protocol
• Reachy Mini Documentation
• Deepgram TTS
• Report Issues