# Reachy Claude MCP
MCP server that brings [Reachy Mini](https://www.pollen-robotics.com/reachy-mini/) to life as your coding companion in [Claude Code](https://claude.ai/claude-code).
Reachy reacts to your coding sessions with emotions, speech, and celebratory dances - making coding more interactive and fun!
## Features
| Feature | Basic | + LLM | + Memory |
|---------|-------|-------|----------|
| Robot emotions & animations | ✅ | ✅ | ✅ |
| Text-to-speech (Piper TTS) | ✅ | ✅ | ✅ |
| Session tracking (SQLite) | ✅ | ✅ | ✅ |
| Smart sentiment analysis | ❌ | ✅ | ✅ |
| AI-generated responses | ❌ | ✅ | ✅ |
| Semantic problem search | ❌ | ❌ | ✅ |
| Cross-project memory | ❌ | ❌ | ✅ |
## Requirements
- Python 3.10+
- [Reachy Mini](https://www.pollen-robotics.com/reachy-mini/) robot **or** the simulation (see below)
- Audio output (speakers/headphones)
### Platform Support
| Platform | Basic | LLM (MLX) | LLM (Ollama) | Memory |
|----------|-------|-----------|--------------|--------|
| macOS Apple Silicon | ✅ | ✅ | ✅ | ✅ |
| macOS Intel | ✅ | ❌ | ✅ | ✅ |
| Linux | ✅ | ❌ | ✅ | ✅ |
| Windows | ⚠️ Experimental | ❌ | ✅ | ✅ |
## Quick Start
1. **Install the package:**
```bash
pip install reachy-claude-mcp
```
2. **Start Reachy Mini simulation** (if you don't have the physical robot):
```bash
# On macOS with Apple Silicon
mjpython -m reachy_mini.daemon.app.main --sim --scene minimal
# On other platforms
python -m reachy_mini.daemon.app.main --sim --scene minimal
```
3. **Add to Claude Code** (`~/.mcp.json`):
```json
{
"mcpServers": {
"reachy-claude": {
"command": "reachy-claude"
}
}
}
```
4. **Start Claude Code** and Reachy will react to your coding!
5. **(Optional) Add instructions for Claude** - Copy [`examples/CLAUDE.md`](examples/CLAUDE.md) to your project root or `~/projects/CLAUDE.md`. This teaches Claude when and how to use Reachy's tools effectively.
## Installation Options
### Basic (robot + TTS only)
```bash
pip install reachy-claude-mcp
```
Without LLM features, Reachy uses keyword matching for sentiment - still works great!
### With LLM (Smart Responses)
**Option A: MLX (Apple Silicon only - fastest)**
```bash
pip install "reachy-claude-mcp[llm]"
```
**Option B: Ollama (cross-platform)**
```bash
# Install Ollama from https://ollama.ai
ollama pull qwen2.5:1.5b
# Then just use the basic install - Ollama is auto-detected
pip install reachy-claude-mcp
```
The system automatically picks the best available backend: MLX → Ollama → keyword fallback.
### Full Features (requires Qdrant)
```bash
pip install "reachy-claude-mcp[all]"
# Start Qdrant vector database
docker compose up -d
```
### Development Install
```bash
git clone https://github.com/mchardysam/reachy-claude-mcp.git
cd reachy-claude-mcp
# Install with all features
pip install -e ".[all]"
# Or specific features
pip install -e ".[llm]" # MLX sentiment analysis (Apple Silicon)
pip install -e ".[memory]" # Qdrant vector store
```
## Running Reachy Mini
### No Robot? Use the Simulation!
You don't need a physical Reachy Mini to use this. The simulation works great:
```bash
# On macOS with Apple Silicon, use mjpython for the MuJoCo GUI
mjpython -m reachy_mini.daemon.app.main --sim --scene minimal
# On Linux/Windows/Intel Mac
python -m reachy_mini.daemon.app.main --sim --scene minimal
```
The simulation dashboard will be available at `http://localhost:8000`.
### Physical Robot
Follow the [Reachy Mini setup guide](https://docs.pollen-robotics.com/reachy-mini/) to connect to your physical robot.
## Configuration
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `REACHY_CLAUDE_HOME` | `~/.reachy-claude` | Data directory for database, memory, voice models |
| **LLM Settings** | | |
| `REACHY_LLM_MODEL` | `mlx-community/Qwen2.5-1.5B-Instruct-4bit` | MLX model (Apple Silicon) |
| `REACHY_OLLAMA_HOST` | `http://localhost:11434` | Ollama server URL |
| `REACHY_OLLAMA_MODEL` | `qwen2.5:1.5b` | Ollama model name |
| **Memory Settings** | | |
| `REACHY_QDRANT_HOST` | `localhost` | Qdrant server host |
| `REACHY_QDRANT_PORT` | `6333` | Qdrant server port |
| **Voice Settings** | | |
| `REACHY_VOICE_MODEL` | *(auto-download)* | Path to custom Piper voice model |
## MCP Tools
### Basic Interactions
| Tool | Description |
|------|-------------|
| `robot_respond` | Speak a summary (1-2 sentences) + play emotion |
| `robot_emotion` | Play emotion animation only |
| `robot_celebrate` | Success animation + excited speech |
| `robot_thinking` | Thinking/processing animation |
| `robot_wake_up` | Start-of-session greeting |
| `robot_sleep` | End-of-session goodbye |
| `robot_oops` | Error acknowledgment |
| `robot_acknowledge` | Quick nod without speaking |
### Dance Moves
| Tool | Description |
|------|-------------|
| `robot_dance` | Perform a dance move |
| `robot_dance_respond` | Dance while speaking |
| `robot_big_celebration` | Major milestone celebration |
| `robot_recovered` | After fixing a tricky bug |
### Smart Features
| Tool | Description |
|------|-------------|
| `process_response` | Auto-analyze output and react appropriately |
| `get_project_greeting` | Context-aware greeting based on history |
| `find_similar_problem` | Search past solutions across projects |
| `store_solution` | Save problem-solution pairs for future |
| `link_projects` | Mark relationships between projects |
### Utilities
| Tool | Description |
|------|-------------|
| `list_robot_emotions` | List available emotions |
| `list_robot_dances` | List available dance moves |
| `get_robot_stats` | Memory statistics across sessions |
| `list_projects` | All projects Reachy remembers |
## Available Emotions
```
amazed, angry, anxious, attentive, bored, calm, celebrate, come, confused,
curious, default, disgusted, done, excited, exhausted, frustrated, go_away,
grateful, happy, helpful, inquiring, irritated, laugh, lonely, lost, loving,
neutral, no, oops, proud, relieved, sad, scared, serene, shy, sleep, success,
surprised, thinking, tired, uncertain, understanding, wake_up, welcoming, yes
```
## Available Dances
**Celebrations:** celebrate, victory, playful, party
**Acknowledgments:** nod, agree, listening, acknowledge
**Reactions:** mind_blown, recovered, fixed_it, whoa
**Subtle:** idle, processing, waiting, thinking_dance
**Expressive:** peek, glance, sharp, funky, smooth, spiral
## Usage Examples
Claude can call these tools during coding sessions:
```python
# After completing a task
robot_respond(summary="Done! Fixed the type error.", emotion="happy")
# When celebrating a win
robot_celebrate(message="Tests are passing!")
# Big milestone
robot_big_celebration(message="All tests passing! Ship it!")
# When starting to think
robot_thinking()
# Session start
robot_wake_up(greeting="Good morning! Let's write some code!")
# Session end
robot_sleep(message="Great session! See you tomorrow.")
```
## Architecture
```
src/reachy_claude_mcp/
├── server.py # MCP server with tools
├── config.py # Centralized configuration
├── robot_controller.py # Reachy Mini control
├── tts.py # Piper TTS (cross-platform)
├── memory.py # Session memory manager
├── database.py # SQLite project tracking
├── vector_store.py # Qdrant semantic search
├── llm_backends.py # LLM backend abstraction (MLX, Ollama)
└── llm_analyzer.py # Sentiment analysis and summarization
```
## Troubleshooting
### Voice model not found
The voice model auto-downloads on first use. If you have issues:
```bash
# Manual download
mkdir -p ~/.reachy-claude/voices
curl -L -o ~/.reachy-claude/voices/en_US-lessac-medium.onnx \
https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx
curl -L -o ~/.reachy-claude/voices/en_US-lessac-medium.onnx.json \
https://huggingface.co/rhasspy/piper-voices/resolve/main/en/en_US/lessac/medium/en_US-lessac-medium.onnx.json
```
### No audio on Linux
Install PulseAudio or ALSA utilities:
```bash
# Ubuntu/Debian
sudo apt install pulseaudio-utils
# Fedora
sudo dnf install pulseaudio-utils
```
### LLM not working
Check which backend is available:
- **MLX**: Only works on Apple Silicon Macs. Install with `pip install "reachy-claude-mcp[llm]"`
- **Ollama**: Make sure Ollama is running (`ollama serve`) and you've pulled a model (`ollama pull qwen2.5:1.5b`)
If neither is available, the system falls back to keyword-based sentiment detection (still works, just less smart).
### Qdrant connection failed
Make sure Qdrant is running:
```bash
docker compose up -d
```
Or point to a remote Qdrant instance:
```bash
export REACHY_QDRANT_HOST=your-qdrant-server.com
```
### Simulation won't start
If `mjpython` isn't found, you may need to install MuJoCo separately or use regular Python:
```bash
# Try without mjpython
python -m reachy_mini.daemon.app.main --sim --scene minimal
```
On Linux, you may need to set `MUJOCO_GL=egl` or `MUJOCO_GL=osmesa` for headless rendering.
## License
MIT
