So101 MCP

🤖 SO101 + MCP 代理 - 完整文档

📋 目录

1. 概述
2. 安装
3. 建筑
4. 使用指南
5. 模块
6. 测试
7. Claude Desktop 集成
8. 故障排除

概述

SO101（LeRobot）机器人与模型上下文协议（MCP）的集成项目，以实现由大型语言模型（LLM）进行控制。

目标

✅ 第一阶段： 设置与架构\ ✅ 第二阶段： 状态管理器（记录/回放）\ ✅ 第三阶段： 序列管理器（动作库）\ ✅ 第四阶段： 单元函数（高级API）\ ✅ 对勾符号（表示正确、同意或完成） 第五阶段： MCP服务器（功能展示）\ ✅ 第六阶段： 集成与测试

技术

• Python 3.10及以上版本
• LeRobot（注：LeRobot可能是一个特定项目、公司或技术的名称，在中文中直接保留原样，不进行翻译） (Hugging Face)
• MCP SDK（MCP软件开发工具包） （模型上下文协议）
• Pydantic （配置）
• SO101 机器人 （6轴跟随臂）

安装

先决条件

# Python 3.10+
python --version

# Git
git --version

安装依赖项

⚠️ 重要提示： 按照此安装顺序进行操作，以避免依赖冲突。

# 1. ÉTAPE OBLIGATOIRE : Installer d'abord le package LeRobot
cd lerobot/
pip install -e .
cd ..

# 2. Installer les requirements LeRobot pour votre système
# Linux/Ubuntu :
pip install -r lerobot/requirements-ubuntu.txt
# macOS :
# pip install -r lerobot/requirements-macos.txt

# 3. Installer les dépendances custom du projet
pip install -r requirements_custom.txt

# 4. Vérifier l'installation
python verify_installation.py
python test_connection.py

注： LeRobot的安装可能需要几分钟时间，因为它包括了PyTorch和其他一些大型依赖项。

配置

1. 复制 .env.example vers（法语）可翻译为中文“朝向”或“向” .env
2. 修改值：

# Robot
SO101_PORT=COM3
SO101_USE_DEGREES=True
SO101_CALIBRATE_ON_CONNECT=False

# Recording
RECORDING_FPS=30
RECORDING_OUTPUT_DIR=custom_modules/state_manager/recordings

# Sequences
SEQUENCE_LIBRARY_DIR=custom_modules/sequences/library

# MCP
MCP_HOST=localhost
MCP_PORT=3000
MCP_LOGGING=True

建筑

SO101 Project
├── lerobot/                    # LeRobot framework
│   └── src/lerobot/
├── custom_modules/             # Custom modules
│   ├── __init__.py
│   ├── config.py              # Pydantic configuration
│   ├── state_manager/         # Phase 2: Recording/Replay
│   │   ├── state_storage.py
│   │   ├── recorder.py
│   │   ├── player.py
│   │   └── recordings/
│   ├── sequences/             # Phase 3: Sequence library
│   │   ├── sequence_manager.py
│   │   └── library/           # Stored sequences
│   └── mcp_agent/             # Phases 4-5: Functions + MCP
│       ├── robot_functions.py
│       └── mcp_server.py
├── main.py                    # Main entry point
├── test_*.py                  # Test scripts
├── create_*.py                # Creation utilities
└── README_PROJECT.md          # This file

数据流

LLM (Claude)
    ↓ MCP Protocol (JSON-RPC)
MCP Server (mcp_server.py)
    ↓ Python Function Calls
RobotFunctions (robot_functions.py)
    ↓ State/Sequence APIs
State Manager + Sequence Manager
    ↓ LeRobot API
SO101 Robot Hardware

使用指南

方法1：主菜单

# Lancer le menu
python main.py

互动菜单，可访问所有功能。

方法2：单独脚本

连接测试

python test_connection.py

录制/回放

python test_record_replay.py

创建序列

# Interactif
python create_sequence.py

# Génération de démos
python create_demo_sequences.py

功能测试

python test_robot_functions.py

MCP服务器

# Mock robot
python custom_modules/mcp_agent/mcp_server.py

# Test du serveur
python test_mcp_server.py

模块

1. 状态管理器（第二阶段）

文件：

• state_storage.py - JSON记录管理
• recorder.py - 录制状态并控制FPS（帧率）
• player.py - 可控速度重放

使用方法：

from custom_modules.state_manager import StateRecorder, StatePlayer

# Enregistrer
recorder = StateRecorder(robot)
recording = recorder.start_recording(duration_s=5.0)

# Rejouer
player = StatePlayer(robot)
player.replay(recording, speed=1.0)

2. 序列管理器（第三阶段）

文件：

• sequence_manager.py - 图书馆管理
• library/ - 已保存的序列（JSON）

使用方法：

from custom_modules.sequences import SequenceManager, Sequence

manager = SequenceManager()

# Lister
sequences = manager.list_sequences(tag="demo")

# Charger
seq = manager.load_sequence("wave_hello")

# Sauvegarder
manager.save_sequence(my_sequence)

3. 机器人功能（第四阶段）

文件： robot_functions.py

API

from custom_modules.mcp_agent import RobotFunctions

funcs = RobotFunctions(robot)

# Lecture
state = funcs.get_current_state()
info = funcs.get_robot_info()
sequences = funcs.list_available_sequences()

# Mouvement
funcs.go_to_rest()
funcs.execute_sequence("wave_hello", speed=1.0)
funcs.move_to_position({"shoulder_pan": 45.0}, gripper=80.0)

# Pince
funcs.open_gripper(100.0)
funcs.close_gripper(0.0)

# Enregistrement
funcs.record_new_sequence("my_seq", duration=5.0, tags=["custom"])

4. MCP服务器（第五阶段）

文件： mcp_server.py

展示的工具： 9个MCP工具

• get_current_state
• get_robot_info
• list_available_sequences
• execute_sequence
• go_to_rest
• move_to_position
• open_gripper
• close_gripper
• record_new_sequence

测试

单元测试

# Connexion robot
python test_connection.py

# Enregistrement/Replay
python test_record_replay.py

# Fonctions robot
python test_robot_functions.py

# Serveur MCP
python test_mcp_server.py

模拟模式

所有的测试都可以运行 无需硬件 多亏了MockRobot。

参数： use_mock=True

集成测试

Le main.py 提供一个菜单来测试完整流程：

1. 测试连接
2. 录制与回放
3. 管理序列
4. 测试函数
5. 启动MCP服务器

Claude Desktop 集成

配置

1. 找到配置文件：

- Windows： %APPDATA%\Claude\claude_desktop_config.json - macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - Linux： ~/.config/Claude/claude_desktop_config.json

1. 添加配置：

{
  "mcpServers": {
    "so101-robot": {
      "command": "python",
      "args": [
        "custom_modules\\mcp_agent\\mcp_server.py"
      ],
      "env": {
        "PYTHONPATH": "custom_modules",
        "SO101_PORT": "COM3",
        "SO101_USE_MOCK": "true"
      }
    }
  }
}

⚠️ 将路径适配到您的系统中！

1. 重启Claude Desktop

提示示例

配置完成后：

"Montre-moi l'état actuel du robot SO101"

"Liste toutes les séquences de mouvement disponibles"

"Exécute la séquence 'wave_hello'"

"Fais lever le bras du robot à 45 degrés et ouvre la pince à 80%"

"Ramène le robot en position de repos"

"Crée une chorégraphie : salut, repos, puis attrape un objet"

克劳德将自动使用MCP工具！

MCP调试

Claude Desktop日志：

• Windows： %APPDATA%\Claude\logs\
• macOS/Linux：查看应用程序控制台

故障排除

常见问题

1. “机器人未连接”

解决方案：

• 检查串口（SO101_PORT 在 .env）
• 检查机器人是否已连接电源
• 与……一起测试 python test_connection.py
• 先尝试使用模拟模式

2. “导入错误：lerobot”

解决方案：

• 检查 pyrightconfig.json (额外路径)
• 安装LeRobot： pip install -e lerobot/
• 检查 PYTHONPATH

3. “序列未找到”

解决方案：

• 列出序列： python -c "from custom_modules.sequences import SequenceManager; print([s.name for s in SequenceManager().list_sequences()])"
• 创建演示： python create_demo_sequences.py
• 检查名称的拼写

4. “MCP服务器无响应”

解决方案：

• 检查Claude Desktop的日志
• 本地测试： python test_mcp_server.py
• 检查JSON配置（路径、语法）
• 重启 Claude Desktop

5. “录制期间出现FPS警告”

原因： CPU太慢，无法保持帧率

解决方案：

• 降低FPS在 .env ： RECORDING_FPS=15
• 关闭其他应用程序
• 使用 time.sleep() 而不是忙等待（见 recorder.py)

调试日志

import logging
logging.basicConfig(level=logging.DEBUG)

或在 .env :

MCP_LOGGING=True

支持

文档：

• LeRobot：https://github.com/huggingface/lerobot
• MCP：https://modelcontextprotocol.io/（可译为：“模型上下文协议（MCP）：https://modelcontextprotocol.io/”）
• SO101： lerobot/docs/source/so101.mdx

问题：

• 检查日志
• 在模拟模式下测试
• 查看每个模块中的README文件

即将进行的改进（第7阶段）

演出

• \[ \] 优化FPS（用于I/O的线程处理）
• \[ \] 在内存中缓存序列
• \[ \] 批处理操作以处理多个动作

功能

• \[ \] 视觉：集成摄像头
• \[ \] 规划：复杂轨迹
• \[ \] 安全：禁行区，限速
• \[ \] UI：用于监控的网页界面

MCP（多用途指挥车）

• \[ \] 更多工具：校准、诊断
• \[ \] 流媒体：实时状态
• \[ \] 多机器人：控制多个SO101

测试

• \[ \] 使用pytest进行单元测试
• \[ \] 持续集成/持续交付（CI/CD）
• \[ \] 性能基准

贡献

这个项目是TEKBOT内部的。要参与贡献：

1. 创建一个特性分支
2. 实施变革
3. 与……一起测试 pytest （当实现时）
4. 创建拉取请求

许可证

遵循LeRobot许可证（Apache 2.0）。

作者

• 埃斯佩朗·艾维瓦洪（注：人名翻译可能因文化和语言习惯不同而有所差异，此译文为一种可能的翻译方式）
• 基于LeRobot（Hugging Face）
• MCP SDK（Anthropic）