SO-ARM100 Robot Control with MCP

Controla los brazos robóticos SO-ARM100 y LeKiwi usando agentes de IA basados en LLM.

GitHub
83
Prueba este MCPPatrocinado

Documentación

Control del Robot SO-ARM100 con MCP

Watch the full tutorial

Un repositorio complementario a mi video sobre el servidor MCP para el robot:

  • Servidor MCP para agentes de IA basados en LLM (Claude Desktop, Cursor, Windsurf, etc.) para controlar el robot
  • Control directo por teclado para operación manual
  • Agente de IA por CLI puede usarlo directamente para controlar el robot con Claude, Gemini o modelos GPT

Si quieres saber más sobre MCP, consulta la documentación oficial de MCP

Se supone que este repositorio funciona con los robots SO-ARM100 / 101. Consulta la guía de configuración de SO-101 de lerobot para obtener instrucciones detalladas sobre cómo configurar el robot.

¡Actualización! Ahora soporta parcialmente LeKiwi (solo el brazo, el control de la base móvil a través de MCP está pendiente). También agregué un agente simple que usa el servidor MCP para controlar el robot. Soporta modelos Claude, Gemini y GPT. En mi experiencia, Claude es el mejor y GPT no es tan bueno, Gemini está en el medio.

Después de publicar el video y este repositorio, LeRobot lanzó una actualización significativa de la biblioteca que rompe la compatibilidad con el código original.

Si quieres usar el código original y seguir exactamente el video, usa esta versión.

Inicio Rápido

1. Instalar Dependencias

Por simplicidad, uso pip simple en lugar de uv, que a menudo se recomienda en los tutoriales de MCP: funciona perfectamente.

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

Puede ser necesario instalar lerobot por separado; simplemente usa las instrucciones oficiales del repositorio de lerobot

2. Conecta Tu Robot

  • Conecta el SO-ARM100 por USB
  • Actualiza config.py con tu puerto serie para so-arm (por ejemplo, /dev/tty.usbmodem58FD0168731) o robot_ip para lekiwi (por ejemplo, 192.168.1.1)
  • Conecta las cámaras y actualiza config.py con los índices y nombres correctos (para lekiwi solo los nombres son importantes)

3. Usa el robot

🔍 Verifica el Estado y la Calibración del Robot:

python check_positions.py

Esto te mostrará el estado actual del robot sin control real. Mueve tu robot manualmente para asegurarte de que esté correctamente calibrado y configurado.

Después de la última actualización, lerobot usa estados de articulaciones normalizados en lugar de grados. Puedes actualizar MOTOR_NORMALIZED_TO_DEGREE_MAPPING en config.py para que coincida con la calibración de tu robot. Deberás actualizar estos valores cada vez que recalibres el robot.

🎮 Control Manual por Teclado:

python keyboard_controller.py

Ahora puedes intentar controlar el robot manualmente usando el teclado. Pruébalo antes de pasar al paso de MCP, para asegurarte de que funcione correctamente.

🛠️ Servidor MCP en modo de desarrollo

mcp dev mcp_robot_server.py

Paso final de prueba: para depurar el servidor MCP, usa la interfaz de usuario para conectarte a él e intenta enviar algunas solicitudes.

🤖 Control del Agente de IA (Servidor MCP):

ADVERTENCIA: usar el servidor MCP en sí es gratuito, pero requiere un cliente MCP que envíe solicitudes a algún LLM. Generalmente no es gratuito, y controlar el robot con MCP puede resultar costoso, ya que envía múltiples solicitudes de agente con imágenes que usan muchos tokens. Asegúrate de comprender y controlar tu uso de tokens y los costos correspondientes antes de hacerlo. El costo real depende del cliente y los modelos que uses, y es tu responsabilidad monitorearlo y controlarlo.

mcp run mcp_robot_server.py --transport SELECTED_TRANSPORT

Soporta: stdio, sse, streamable-http

Ahora tu servidor se puede agregar a cualquier cliente MCP.

Conexión de Clientes MCP

Diferentes clientes pueden soportar diferentes transportes; puedes elegir el que mejor funcione para ti. La funcionalidad es la misma.

Transporte STDIO

Agrega a tu configuración de MCP:

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

Transporte SSE

Ejecuta el servidor en la terminal con el transporte SSE:

mcp run mcp_robot_server.py --transport sse

Agrega a tu configuración de MCP:

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

Transporte Streamed-HTTP

Se supone que es un reemplazo para SSE, pero actualmente no muchos clientes lo soportan.

Ejecuta el servidor en la terminal con el transporte Streamed-HTTP:

mcp run mcp_robot_server.py --transport streamable-http

Agrega a tu configuración de MCP:

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

Usando el robot con MCP

Ahora puedes ir a tu cliente y debería poder controlar el robot cuando le des instrucciones en lenguaje natural.

Usando el Agente

Inicia el servidor MCP con el transporte SSE:

mcp run mcp_robot_server.py --transport sse

Ahora puedes usar el agente de IA para controlar el robot con instrucciones en lenguaje natural.

Configuración

Crea un archivo .env en la raíz del proyecto con tus claves 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 Avanzado

# 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 Soportados (ejemplos)

Claude (Anthropic):

  • claude-3-7-sonnet-latest (predeterminado)
  • Todos los modelos soportan pensamiento, transmisión y resultados de herramientas multimodales

Gemini (Google):

  • gemini-2.5-flash
  • gemini-2.5-pro
  • Usa modelos 2.5+ ya que soportan la función de pensamiento

GPT (OpenAI):

  • gpt-4o y variantes
  • El resto de los modelos en su mayoría no soportan pensamiento o llamadas a herramientas.

En general, no logré obtener buenos resultados con los modelos GPT.

Parámetros

  • --model: Modelo LLM a usar (predeterminado: claude-3-7-sonnet-latest)
  • --api-key: Anulación de clave de API (usa el archivo .env por defecto)
  • --show-images: Mostrar imágenes de la cámara del robot en una ventana
  • --thinking-budget: Presupuesto de tokens de pensamiento (predeterminado: 1024, 0 para desactivar)
  • --thinking-every-n: Usar pensamiento cada N pasos (predeterminado: 3)
  • --mcp-server-ip: Dirección IP del servidor MCP (predeterminado: 127.0.0.1)
  • --mcp-port: Puerto del servidor MCP (predeterminado: 3001)

Consideraciones de Costo

Uso de Tokens:

  • Claude cuenta las imágenes de MCP en los tokens de entrada (más costoso para tareas de visión)
  • Gemini no cuenta las imágenes de MCP en los tokens (el uso de tokens se mostrará solo para texto)
  • Los tokens de pensamiento aumentan el costo pero mejoran la calidad del razonamiento