reachy-mini-mcp

Controla el robot Reachy Mini (o el simulador) desde Claude, ChatGPT o cualquier cliente compatible con MCP.

Documentación

Reachy Mini MCP

Controla el robot Reachy Mini (o el simulador) desde Claude, ChatGPT o cualquier cliente compatible con MCP.

Inicio rápido

uv sync --extra reachy
uv run reachy.py

Demo del simulador

uv sync --extra reachy-sim
uv run python reachy_debug.py

Prueba en seco (video)

Una "prueba en seco" corta del ejecutor de demos secuenciales reachy_debug.py (simulador): anuncios de pasos, movimientos, visión y artefactos.

Tu navegador no puede reproducir este video. Descargar MP4.

Mira el video de prueba en seco en GitHub Pages

Cómo funciona

AI Assistant  --stdio-->  MCP Server (reachy.py)  -->  ReachyMini SDK  -->  Robot / Simulator

El servidor expone 16 herramientas, 4 prompts y 4 recursos a través del Model Context Protocol. Un asistente de IA llama a estas herramientas para ver a través de la cámara del robot, mover el robot, expresar emociones, reproducir sonidos o detectar la dirección del audio, sin necesidad de conocimientos de robótica por parte de la IA.

Instalación

Requisitos previos

Python 3.13+
Robot Reachy Mini o el simulador Reachy Mini
uv (recomendado) o pip

Instalar el servidor

git clone https://github.com/ArturSkowronski/reachy-mini-mcp.git
cd reachy-mini-mcp
uv sync

O con pip:

pip install -e .

Configurar tu cliente MCP

Añade el servidor a la configuración de tu cliente MCP. La ubicación exacta depende del cliente:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

{
  "mcpServers": {
    "reachy-mini": {
      "command": "uv",
      "args": ["--directory", "/path/to/reachy-mini-mcp", "run", "reachy.py"]
    }
  }
}

Claude Code (.mcp.json en la raíz de tu proyecto):

{
  "mcpServers": {
    "reachy-mini": {
      "command": "uv",
      "args": ["--directory", "/path/to/reachy-mini-mcp", "run", "reachy.py"]
    }
  }
}

Transporte stdio genérico:

uv run reachy.py

ElevenLabs TTS (opcional)

Para habilitar la herramienta speak_text, configura estas variables de entorno:

export ELEVENLABS_API_KEY="your-api-key"
export ELEVENLABS_VOICE_ID="your-voice-id"
#
# Optional override prefix (takes precedence):
# export REACHY_ELEVENLABS_API_KEY="your-api-key"
# export REACHY_ELEVENLABS_VOICE_ID="your-voice-id"

Voz predeterminada (compatible con el nivel gratuito): George con Voice ID JBFqnCBsd6RMkjVDRZzb.

Voz favorita (preferencia del autor): Horatius con Voice ID qXpMhyvQqiRxWQs4qSSB.

Anulaciones opcionales: ELEVENLABS_MODEL_ID (predeterminado: eleven_multilingual_v2), ELEVENLABS_OUTPUT_FORMAT (predeterminado: mp3_44100_128).

Soporte WAV: si tu plan de ElevenLabs lo permite, puedes configurar ELEVENLABS_OUTPUT_FORMAT=wav_44100 para obtener salida WAV en lugar de MP3.

Nota sobre reproducción MP3 vs WAV

La salida TTS predeterminada es MP3 (mp3_44100_128) porque funciona en los niveles más bajos de ElevenLabs.
Algunos backends/entornos de audio de Reachy pueden no tener decodificación MP3 disponible. En ese caso, la reproducción MP3 puede fallar aunque WAV funcione.
Si necesitas que ElevenLabs devuelva WAV directamente (wav_44100), ElevenLabs requiere un nivel superior (mínimo Pro).
Para forzar la salida WAV (cuando esté disponible), anula el formato de salida mediante variables de entorno:
- REACHY_ELEVENLABS_OUTPUT_FORMAT=wav_44100 (preferido, tiene prioridad)
- o ELEVENLABS_OUTPUT_FORMAT=wav_44100

Variables de entorno

Generales:

NO_COLOR: desactiva los colores ANSI en la salida de reachy_debug.py.

Ejecutor de depuración (reachy_debug.py):

REACHY_DEBUG_ANNOUNCE_PAUSE_S (predeterminado: 0.6): pausa después de cada anuncio antes de ejecutar el paso.
REACHY_DEBUG_TTS_SPEED (predeterminado: 0.8): velocidad de habla de ElevenLabs.

ElevenLabs (usado por anuncios de speak_text y reachy_debug.py):

REACHY_ELEVENLABS_API_KEY o ELEVENLABS_API_KEY (requerido para TTS): clave API. El valor con prefijo REACHY_ tiene prioridad.
REACHY_ELEVENLABS_VOICE_ID o ELEVENLABS_VOICE_ID (opcional): ID de voz. Predeterminado a JBFqnCBsd6RMkjVDRZzb (George) si no se configura.
REACHY_ELEVENLABS_MODEL_ID o ELEVENLABS_MODEL_ID (opcional): ID de modelo (predeterminado: eleven_multilingual_v2).
REACHY_ELEVENLABS_OUTPUT_FORMAT o ELEVENLABS_OUTPUT_FORMAT (opcional): formato de salida (predeterminado: mp3_44100_128, opcionalmente wav_44100 si tu plan lo permite).

Herramientas disponibles

Herramienta	Descripción
`capture_image`	Captura un fotograma JPEG de la cámara HD del robot
`scan_surroundings`	Panorámica de la cámara en múltiples ángulos y devuelve un conjunto panorámico de imágenes
`track_face`	Detecta una cara mediante OpenCV y gira la cabeza para mirarla
`move_head`	Posicionamiento de cabeza de 6 DOF (x/y/z en mm, roll/pitch/yaw en grados)
`move_antennas`	Control independiente de antenas (-3.14 a 3.14 radianes)
`look_at_point`	Orienta la cabeza hacia un punto 3D en coordenadas del mundo
`express_emotion`	Sistema de emociones basado en emojis con movimientos y sonidos sincronizados
`play_sound`	Reproduce sonidos integrados (wake_up, go_sleep, confused1, impatient1, dance1, count)
`speak_text`	Texto a voz mediante la API de ElevenLabs, reproducido a través del altavoz del robot
`detect_sound_direction`	Dirección de llegada del micrófono en matriz + detección de voz
`wake_up`	Animación de saludo integrada con sonido
`go_to_sleep`	Animación de despedida integrada con sonido
`nod`	Asiente con la cabeza hacia arriba y abajo para indicar "sí" o acuerdo
`shake_head`	Mueve la cabeza de izquierda a derecha para indicar "no" o desacuerdo
`reset_position`	Devuelve la cabeza y las antenas a la postura de reposo neutral
`do_barrel_roll`	Secuencia coreografiada de inclinación de cabeza + movimiento de antenas

Recursos

El servidor también expone recursos MCP que permiten a los asistentes de IA descubrir las capacidades del robot dinámicamente:

URI del recurso	Descripción
`reachy://emotions`	Mapeos de emoji a emoción compatibles
`reachy://sounds`	Nombres de sonidos integrados disponibles
`reachy://limits`	Límites físicos (rango de antenas, DOF de cabeza, especificaciones de cámara)
`reachy://capabilities`	Todas las herramientas agrupadas por categoría (visión, movimiento, expresión, audio, ciclo de vida)

Visión

capture_image captura un fotograma de la cámara HD gran angular de Reachy Mini y lo devuelve como contenido JPEG en línea a través del protocolo MCP. El asistente de IA recibe la imagen directamente en la conversación, sin rutas de archivo, sin URLs, sin configuración adicional.

scan_surroundings va más allá al hacer una panorámica de la cámara en múltiples ángulos y devolver todos los fotogramas en una sola respuesta:

User:  "Look around and describe the room"

       Claude calls scan_surroundings(steps=5, yaw_range=120)
       <- Robot pans from -60deg to +60deg in 5 steps
       <- MCP returns 5 labeled JPEG frames + summary text

Claude: "Starting from the left I can see a window with blinds,
         then a whiteboard, your desk with two monitors in the
         center, a bookshelf to the right, and a door at the
         far right."

La cámara devuelve un fotograma numpy BGR estándar de OpenCV, que se comprime en JPEG y se entrega como MCP ImageContent. Cualquier modelo de IA multimodal que admita entradas de imagen puede procesarlo: Claude, GPT-4o, Gemini, etc.

Anotaciones de herramientas

Cada herramienta lleva anotaciones semánticas que indican a los clientes de IA cómo usarla de forma segura:

Anotación	Significado	Herramientas
`readOnlyHint`	No cambia el estado del robot	`capture_image`, `detect_sound_direction`
`idempotentHint=true`	Seguro de llamar repetidamente	`capture_image`, `detect_sound_direction`
`idempotentHint=false`	Las llamadas repetidas repiten acciones/costos	Todas las herramientas de movimiento/gesto/audio, incluyendo `speak_text`
`destructiveHint=false`	Sin acciones irreversibles	Todas las herramientas
`openWorldHint`	Llama a servicios externos	`speak_text` (API de ElevenLabs)

Prompts

Plantillas de prompts preconstruidas que guían a los asistentes de IA en escenarios comunes de interacción con robots:

Prompt	Descripción
`greet_user`	Despierta el robot, expresa felicidad y saluda por nombre
`explore_room`	Escanea el entorno con la cámara y describe el ambiente
`react_to_conversation`	Usa gestos y emociones para reaccionar físicamente durante el chat
`find_person`	Usa la cámara y el seguimiento facial para localizar y seguir a una persona

Sistema de emociones

express_emotion mapea caracteres emoji a movimientos coreografiados:

Emoji	Emoción	Comportamiento
`😊`	feliz	antenas arriba, postura alegre, sonido de baile
`😕`	confundido	inclinación de cabeza, antenas asimétricas, sonido de confusión
`😤`	impaciente	movimientos rápidos de antenas, sonido de impaciencia
`😴`	somnoliento	postura de sueño con sonido
`👋`	saludo	animación de despertar
`🤔`	pensativo	inclinación contemplativa de cabeza, antenas extendidas
`😮`	sorprendido	antenas altas, cabeza hacia atrás
`😢`	triste	antenas y cabeza hacia abajo
`🎉`	celebrar	movimiento enérgico, sonido de baile
`😐`	neutral	volver a la posición de reposo

Desarrollo

# Install with dev dependencies
uv sync --extra dev

# Run all tests
uv run pytest -v

# Unit tests only
uv run pytest -v -m "not integration"

# Integration tests only (MCP protocol layer)
uv run pytest -v -m integration

# Lint
uv run ruff check . && uv run ruff format --check .

# Set up pre-commit hooks
pre-commit install

Pruebas directas del robot

Para una demo de depuración secuencial completa de un solo clic (movimiento, gestos, audio, visión, seguimiento) con verificaciones de estado por paso:

uv sync --extra reachy
# If you want to auto-spawn the simulator daemon, also install:
uv sync --extra reachy-sim
uv run python reachy_debug.py

reachy_debug.py ahora:

Anuncia cada paso de prueba próximo (voz mediante ElevenLabs si está configurado, de lo contrario respaldo por consola).
Ejecuta una suite de demos completa en secuencia.
Guarda todas las imágenes capturadas y un resumen de ejecución en markdown en results/run-YYYYMMDD-HHMMSS/.
Genera un único archivo de informe para la ejecución: run_report.md.

GitHub Pages

Este repositorio incluye un sitio estático de GitHub Pages en docs/ (con el video de prueba en seco incrustado).

Para publicar: Configuración del repositorio de GitHub -> Pages -> "Build and deployment" -> Source: "Deploy from a branch" -> Branch: main -> Folder: /docs.