SO-ARM100 Robot Control with MCP

Controle os braços robóticos SO-ARM100 e LeKiwi usando agentes de IA baseados em LLM.

GitHub
83
Experimente este MCPPatrocinado

Documentação

SO-ARM100 Robot Control with MCP

Watch the full tutorial

Um repositório complementar ao meu vídeo sobre o servidor MCP para o robô:

  • Servidor MCP para agentes de IA baseados em LLM (Claude Desktop, Cursor, Windsurf, etc.) controlarem o robô
  • Controle direto por teclado para operação manual
  • Agente de IA via CLI pode usá-lo diretamente para controlar o robô com modelos Claude, Gemini ou GPT

Se você quiser saber mais sobre MCP, consulte a documentação oficial do MCP

Este repositório foi feito para funcionar com os robôs SO-ARM100 / 101. Consulte o guia de configuração do SO-101 do lerobot para instruções detalhadas sobre como configurar o robô.

Atualização! Agora há suporte parcial para LeKiwi (apenas o braço, o controle da base móvel via MCP está pendente). Também adicionei um agente simples que usa o servidor MCP para controlar o robô. Ele suporta modelos Claude, Gemini e GPT. Na minha experiência, o Claude é o melhor, o GPT não é tão bom e o Gemini fica no meio termo.

Depois que publiquei o vídeo e este repositório, o LeRobot lançou uma atualização significativa da biblioteca que quebra a compatibilidade com o código original.

Se você quiser usar o código original e seguir exatamente o vídeo, use esta versão.

Início Rápido

1. Instalar Dependências

Para simplificar, uso pip simples em vez de uv, que é frequentemente recomendado nos tutoriais de MCP — funciona perfeitamente.

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

Pode ser necessário instalar o lerobot separadamente; basta usar as instruções oficiais do repositório do lerobot

2. Conectar Seu Robô

  • Conecte o SO-ARM100 via USB
  • Atualize config.py com sua porta serial para o so-arm (ex.: /dev/tty.usbmodem58FD0168731) ou robot_ip para lekiwi (ex.: 192.168.1.1)
  • Conecte as câmeras e atualize config.py com os índices e nomes corretos (para lekiwi apenas os nomes são importantes)

3. Usar o robô

🔍 Verificar Status e Calibração do Robô:

python check_positions.py

Isso mostrará o estado atual do robô sem controle real. Mova seu robô manualmente para garantir que ele esteja devidamente calibrado e configurado.

Após a última atualização, o lerobot usa estados de juntas normalizados em vez de graus. Você pode atualizar MOTOR_NORMALIZED_TO_DEGREE_MAPPING em config.py para corresponder à calibração do seu robô. Você precisará atualizar esses valores toda vez que recalibrar o robô.

🎮 Controle Manual por Teclado:

python keyboard_controller.py

Agora você pode tentar controlar o robô manualmente usando o teclado. Teste antes de passar para a etapa do MCP para garantir que tudo funcione corretamente.

🛠️ Servidor MCP no modo de desenvolvimento

mcp dev mcp_robot_server.py

Etapa final de teste — para depurar o servidor MCP, use a interface para conectar-se a ele e tente enviar algumas solicitações.

🤖 Controle por Agente de IA (Servidor MCP):

AVISO: usar o próprio servidor MCP é gratuito, mas ele requer um cliente MCP que envie solicitações para algum LLM. Geralmente isso não é gratuito — e controlar o robô com MCP pode ficar caro, pois envia múltiplas solicitações de agente com imagens que consomem muitos tokens. Certifique-se de entender e controlar seu uso de tokens e os custos correspondentes antes de fazer isso. O custo real depende do cliente e dos modelos que você usa, e é sua responsabilidade monitorar e controlar isso.

mcp run mcp_robot_server.py --transport SELECTED_TRANSPORT

Suporta: stdio, sse, streamable-http

Agora seu servidor pode ser adicionado a qualquer cliente MCP.

Conectando Clientes MCP

Diferentes clientes podem suportar diferentes transportes; você pode escolher o que funciona melhor para você. A funcionalidade é a mesma.

Transporte STDIO

Adicione à sua configuração MCP:

{
  "mcpServers": {
    "SO-ARM100 robot controller": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/mcp_robot_server.py"]
    }
  }
}

Transporte SSE

Execute o servidor no terminal com o transporte SSE:

mcp run mcp_robot_server.py --transport sse

Adicione à sua configuração MCP:

{
  "mcpServers": {
    "SO-ARM100 robot controller": {
      "url": "http://127.0.0.1:3001/sse"
    }
  }
}

Transporte Streamed-HTTP

Ele deve ser um substituto para o SSE, mas atualmente não muitos clientes o suportam.

Execute o servidor no terminal com o transporte Streamed-HTTP:

mcp run mcp_robot_server.py --transport streamable-http

Adicione à sua configuração MCP:

{
  "mcpServers": {
    "SO-ARM100 robot controller": {
      "url": "http://127.0.0.1:3001/mcp"
    }
  }
}

Usando o robô com MCP

Agora você pode ir ao seu cliente e ele deve ser capaz de controlar o robô quando você der instruções em linguagem natural.

Usando o Agente

Inicie o servidor MCP com o transporte SSE:

mcp run mcp_robot_server.py --transport sse

Agora você pode usar o agente de IA para controlar o robô com instruções em linguagem natural.

Configuração

Crie um arquivo .env na raiz do projeto com suas chaves de API:

# API Keys (at least one required)
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GEMINI_API_KEY=your_gemini_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# MCP Server Configuration (optional)
MCP_SERVER_IP=127.0.0.1
MCP_PORT=3001

Uso Básico

python agent.py

Uso Avançado

# Use Gemini instead of Claude
python agent.py --model gemini-2.5-flash

# Override API key
python agent.py --api-key your_api_key_here

# Enable image viewer window
python agent.py --show-images

# Increase thinking budget for better reasoning
python agent.py --thinking-budget 2048

# Custom MCP server location
python agent.py --mcp-server-ip 192.168.1.100 --mcp-port 3002

Modelos Suportados (exemplos)

Claude (Anthropic):

  • claude-3-7-sonnet-latest (padrão)
  • Todos os modelos suportam raciocínio, streaming e resultados de ferramentas multimodais

Gemini (Google):

  • gemini-2.5-flash
  • gemini-2.5-pro
  • Use modelos 2.5+ pois eles suportam o recurso de raciocínio

GPT (OpenAI):

  • gpt-4o e variantes
  • Os demais modelos em sua maioria não suportam raciocínio ou chamada de ferramentas.

No geral, não consegui obter bons resultados com os modelos GPT.

Parâmetros

  • --model: Modelo LLM a usar (padrão: claude-3-7-sonnet-latest)
  • --api-key: Substituição da chave de API (usa o arquivo .env por padrão)
  • --show-images: Exibir imagens da câmera do robô em uma janela
  • --thinking-budget: Orçamento de tokens de raciocínio (padrão: 1024, 0 para desativar)
  • --thinking-every-n: Usar raciocínio a cada N etapas (padrão: 3)
  • --mcp-server-ip: Endereço IP do servidor MCP (padrão: 127.0.0.1)
  • --mcp-port: Porta do servidor MCP (padrão: 3001)

Considerações de Custo

Uso de Tokens:

  • O Claude conta imagens do MCP nos tokens de entrada (mais caro para tarefas de visão)
  • O Gemini não conta imagens do MCP nos tokens (o uso de tokens será exibido apenas para texto)
  • Tokens de raciocínio aumentam o custo, mas melhoram a qualidade do raciocínio