reachy-mini-mcp

Controle o robô Reachy Mini (ou simulador) a partir do Claude, ChatGPT ou qualquer cliente compatível com MCP.

Documentação

Reachy Mini MCP

Controle o robô Reachy Mini (ou o simulador) a partir do Claude, ChatGPT ou qualquer cliente compatível com MCP.

Início rápido

uv sync --extra reachy
uv run reachy.py

Demonstração no simulador

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

Execução de teste (vídeo)

Uma "execução de teste" curta do reachy_debug.py executor de demonstração sequencial (simulador): anúncios de etapas, movimentos, visão e artefatos.

Seu navegador não consegue reproduzir este vídeo. Baixar MP4.

Assista ao vídeo da execução de teste no GitHub Pages

Como funciona

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

O servidor expõe 16 ferramentas, 4 prompts e 4 recursos por meio do Model Context Protocol. Um assistente de IA chama essas ferramentas para enxergar pela câmera do robô, mover o robô, expressar emoções, reproduzir sons ou detectar direção de áudio — sem necessidade de conhecimento em robótica do lado da IA.

Instalação

Pré-requisitos

Python 3.13+
Robô Reachy Mini ou o simulador Reachy Mini
uv (recomendado) ou pip

Instalar o servidor

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

Ou com pip:

pip install -e .

Configurar seu cliente MCP

Adicione o servidor à configuração do seu cliente MCP. A localização exata depende do cliente:

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

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

Claude Code (.mcp.json na raiz do seu projeto):

{
  "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 a ferramenta speak_text, defina estas variáveis de ambiente:

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 padrão (compatível com plano gratuito): George com Voice ID JBFqnCBsd6RMkjVDRZzb.

Voz favorita (preferência do autor): Horatius com Voice ID qXpMhyvQqiRxWQs4qSSB.

Substituições opcionais: ELEVENLABS_MODEL_ID (padrão: eleven_multilingual_v2), ELEVENLABS_OUTPUT_FORMAT (padrão: mp3_44100_128).

Suporte a WAV: se seu plano ElevenLabs permitir, você pode definir ELEVENLABS_OUTPUT_FORMAT=wav_44100 para obter saída WAV em vez de MP3.

Nota sobre reprodução MP3 vs WAV

A saída padrão de TTS é MP3 (mp3_44100_128) porque funciona em níveis mais baixos do ElevenLabs.
Alguns backends/ambientes de áudio do Reachy podem não ter decodificação de MP3 disponível. Nesse caso, a reprodução de MP3 pode falhar mesmo quando WAV funciona.
Se você precisar que o ElevenLabs retorne WAV diretamente (wav_44100), o ElevenLabs exige um nível superior (mínimo Pro).
Para forçar a saída WAV (quando disponível), substitua o formato de saída por meio de variáveis de ambiente:
- REACHY_ELEVENLABS_OUTPUT_FORMAT=wav_44100 (preferido, tem precedência)
- ou ELEVENLABS_OUTPUT_FORMAT=wav_44100

Variáveis de ambiente

Gerais:

NO_COLOR: desativa cores ANSI na saída de reachy_debug.py.

Executor de depuração (reachy_debug.py):

REACHY_DEBUG_ANNOUNCE_PAUSE_S (padrão: 0.6): pausa após cada anúncio antes de executar a etapa.
REACHY_DEBUG_TTS_SPEED (padrão: 0.8): velocidade de fala do ElevenLabs.

ElevenLabs (usado pelos anúncios de speak_text e reachy_debug.py):

REACHY_ELEVENLABS_API_KEY ou ELEVENLABS_API_KEY (obrigatório para TTS): chave da API. O valor com prefixo REACHY_ tem precedência.
REACHY_ELEVENLABS_VOICE_ID ou ELEVENLABS_VOICE_ID (opcional): ID da voz. Padrão: JBFqnCBsd6RMkjVDRZzb (George) se não definido.
REACHY_ELEVENLABS_MODEL_ID ou ELEVENLABS_MODEL_ID (opcional): ID do modelo (padrão: eleven_multilingual_v2).
REACHY_ELEVENLABS_OUTPUT_FORMAT ou ELEVENLABS_OUTPUT_FORMAT (opcional): formato de saída (padrão: mp3_44100_128, opcionalmente wav_44100 se seu plano permitir).

Ferramentas disponíveis

Ferramenta	Descrição
`capture_image`	Captura um quadro JPEG da câmera HD do robô
`scan_surroundings`	Movimenta a câmera em vários ângulos e retorna um conjunto panorâmico de imagens
`track_face`	Detecta um rosto via OpenCV e vira a cabeça para encará-lo
`move_head`	Posicionamento de cabeça com 6 graus de liberdade (x/y/z em mm, roll/pitch/yaw em graus)
`move_antennas`	Controle independente das antenas (-3,14 a 3,14 radianos)
`look_at_point`	Orienta a cabeça em direção a um ponto 3D em coordenadas do mundo
`express_emotion`	Sistema de emoções baseado em emojis com movimentos e sons sincronizados
`play_sound`	Reproduz sons integrados (wake_up, go_sleep, confused1, impatient1, dance1, count)
`speak_text`	Texto para fala via API ElevenLabs, reproduzido pelo alto-falante do robô
`detect_sound_direction`	Matriz de microfones com detecção de direção de chegada + detecção de fala
`wake_up`	Animação de saudação integrada com som
`go_to_sleep`	Animação de despedida integrada com som
`nod`	Move a cabeça para cima e para baixo indicando "sim" ou concordância
`shake_head`	Move a cabeça para os lados indicando "não" ou discordância
`reset_position`	Retorna cabeça e antenas à posição neutra de descanso
`do_barrel_roll`	Sequência coreografada de inclinação de cabeça + movimento das antenas

Recursos

O servidor também expõe recursos MCP que permitem que assistentes de IA descubram capacidades do robô dinamicamente:

URI do recurso	Descrição
`reachy://emotions`	Mapeamentos suportados de emoji para emoção
`reachy://sounds`	Nomes de sons integrados disponíveis
`reachy://limits`	Limites físicos (alcance das antenas, graus de liberdade da cabeça, especificações da câmera)
`reachy://capabilities`	Todas as ferramentas agrupadas por categoria (visão, movimento, expressão, áudio, ciclo de vida)

Visão

capture_image captura um quadro da câmera HD grande angular do Reachy Mini e o retorna como conteúdo JPEG inline pelo protocolo MCP. O assistente de IA recebe a imagem diretamente na conversa — sem caminhos de arquivo, sem URLs, sem configuração extra.

scan_surroundings vai além ao movimentar a câmera em vários ângulos e retornar todos os quadros em uma única resposta:

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

A câmera retorna um quadro numpy BGR padrão do OpenCV, que é comprimido em JPEG e entregue como MCP ImageContent. Qualquer modelo de IA multimodal que suporte entrada de imagens pode processá-lo — Claude, GPT-4o, Gemini, etc.

Anotações de ferramentas

Cada ferramenta carrega anotações semânticas que informam aos clientes de IA como usá-la com segurança:

Anotação	Significado	Ferramentas
`readOnlyHint`	Não altera o estado do robô	`capture_image`, `detect_sound_direction`
`idempotentHint=true`	Seguro chamar repetidamente	`capture_image`, `detect_sound_direction`
`idempotentHint=false`	Chamadas repetidas repetem ações/custos	Todas as ferramentas de movimento/gesto/áudio, incluindo `speak_text`
`destructiveHint=false`	Sem ações irreversíveis	Todas as ferramentas
`openWorldHint`	Chama serviços externos	`speak_text` (API ElevenLabs)

Prompts

Modelos de prompt pré-construídos que guiam assistentes de IA em cenários comuns de interação com o robô:

Prompt	Descrição
`greet_user`	Acordar o robô, expressar felicidade e cumprimentar pelo nome
`explore_room`	Escanear o ambiente com a câmera e descrever o entorno
`react_to_conversation`	Usar gestos e emoções para reagir fisicamente durante o chat
`find_person`	Usar câmera e rastreamento facial para localizar e seguir uma pessoa

Sistema de emoções

express_emotion mapeia caracteres de emoji para movimentos coreografados:

Emoji	Emoção	Comportamento
`😊`	feliz	antenas para cima, pose alegre, som de dança
`😕`	confuso	inclinação de cabeça, antenas assimétricas, som de confusão
`😤`	impaciente	movimentos rápidos de antena, som de impaciência
`😴`	sonolento	pose de sono com som
`👋`	saudação	animação de despertar
`🤔`	pensativo	inclinação contemplativa de cabeça, antenas abertas
`😮`	surpreso	antenas altas, cabeça para trás
`😢`	triste	antenas e cabeça para baixo
`🎉`	comemorar	movimento enérgico, som de dança
`😐`	neutro	retornar à posição de descanso

Desenvolvimento

# 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

Teste direto do robô

Para uma demonstração de depuração sequencial completa com um clique (movimento, gestos, áudio, visão, rastreamento) com verificações de status por etapa:

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 agora:

Anuncia cada etapa de teste futura (voz via ElevenLabs se configurado, caso contrário fallback no console).
Executa uma suíte de demonstração completa em sequência.
Salva todas as imagens capturadas e um resumo da execução em markdown em results/run-YYYYMMDD-HHMMSS/.
Gera um único arquivo de relatório para a execução: run_report.md.

GitHub Pages

Este repositório inclui um site estático do GitHub Pages em docs/ (com o vídeo da execução de teste incorporado).

Para publicar: Configurações do repositório no GitHub -> Pages -> "Build and deployment" -> Fonte: "Deploy from a branch" -> Branch: main -> Pasta: /docs.