内容
# unitree-mcp
**Unitree 机器人通过 MCP: Go2 四足机器人，H1/H1-2/G1 人形机器人。MuJoCo 仿真，ROS 2.**
[](https://github.com/sandraschi/unitree-mcp/actions/workflows/ci.yml)
[](https://github.com/astral-sh/ruff)
[](https://github.com/jlowin/fastmcp)
[](https://www.python.org)
[](LICENSE)
unitree-mcp 为 Unitree 所有的机器人产品线提供 MCP 工具：Go2 四足机器人（狗），H1/H1-2 两足机器人，和 G1 全尺寸人形机器人。加载预调的 MJCF 模型到 MuJoCo，控制关节位置和步态参数，流式传输遥测数据，并部署策略 — 所有这些都通过 14 个 MCP 工具。服务器包括一个机器人模型仓库，一个步态库，以及用于 ROS 2 和 Unitree SDK 的桥接脚本。
为舰队仿真管道而构建：unitree-mcp 模型可被 mujoco-mcp 用于物理，ros-mcp 用于 ROS 2 主题控制，isaac-mcp 用于 GPU 加速训练。
## 目录
- [快速入门](#快速入门)
- [工具](#工具)
- [架构](#架构)
- [文档](#文档)
- [端口](#端口)
- [脚注](#脚注)
## 快速入门
```powershell
# 1. 克隆并进入
git clone https://github.com/sandraschi/unitree-mcp
cd unitree-mcp
# 2. 运行 MCP 服务器
uv run python -m unitree_mcp
# 3. 或启动完整的 Web 控制台
.\start.ps1
```
## 工具
| # | 工具 | 描述 |
|---|------|-------------|
| 1 | `sim_status` | 健康检查 — 机器人模型加载，活动作业，ROS 2 桥接状态 |
| 2 | `load_model` | 加载 Unitree 机器人模型（Go2，H1，H1-2，G1）到仓库 |
| 3 | `start_sim` | 启动仿真，选用机器人模型和步态配置 |
| 4 | `stop_sim` | 停止仿真 |
| 5 | `get_state` | 读取关节位置，IMU 数据，脚部接触状态 |
| 6 | `apply_control` | 应用关节目标或步态命令（速度，站立高度，步频） |
| 7 | `list_models` | 列出仓库中所有 Unitree 机器人模型及其配置元数据 |
| 8 | `list_jobs` | 列出活动和已完成的仿真作业 |
| 9 | `export_frame` | 导出渲染帧为 PNG |
| 10 | `agentic_sim_workflow` | 通过 LLM 采样进行多步骤机器人工作流 |
| 11 | `natural_language_control` | 通过自然语言控制机器人（“缓慢向前走”） |
| 12 | `analyze_sim_state` | 步态分析 — 脚部间隙，关节扭矩限制，稳定性裕度 |
| 13 | `analyze_sim_logs` | 解析仿真日志中的步态失败，电机饱和，接触丢失 |
| 14 | `discover_model` | 搜索和下载 Unitree 模型和步态配置 |
[完整工具参考 →](docs/TOOLS.md)
## 架构
unitree-mcp 封装了三个后端：MuJoCo（默认），Gazebo（通过 ros-mcp 桥接），或真实的 Unitree SDK（`unitree_sdk2` 用于硬件）。机器人模型仓库存储了为每个 Unitree 变体预调的 MJCF 配置。步态模式参数化（站立高度，步频，摆动幅度），可以在运行时交换。
```
MCP 客户端 ──► unitree-mcp (FastMCP 3.2)
│
┌─────────┴──────────────┐
│ 步态控制器 │
│ (参数化步态) │
└─────────┬──────────────┘
│
┌───────────────┼───────────────┐
│ │ │
MuJoCo 后端 Gazebo 桥接 Unitree SDK
(mujoco-mcp) (ros-mcp) (硬件)
```
[架构深入解析 →](docs/SIM_SETUP.md)
## 文档
| 文档 | 内容 |
|-----|----------|
| `docs/TOOLS.md` | 所有 14 个工具的完整参考，包含输入，输出，示例 |
| `docs/SETUP.md` | 安装，Unitree SDK 设置，步态配置，故障排除 |
| `docs/SIM_SETUP.md` | 后端选择，ROS 2 桥接配置，硬件启动 |
## 端口
| 端口 | 服务 |
|------|---------|
| 11052 | FastAPI 后端 + MCP HTTP |
| 11053 | Vite React 前端 |
## 脚注
[^1]: **Unitree** — 中国领先的机器人公司。产品：Go2 四足机器人，H1/H1-2 两足机器人，G1 人形机器人。[unitree.com](https://unitree.com)
[^2]: **MJCF** — MuJoCo XML 格式。MuJoCo 物理的原生模型格式。Unitree 机器人的预调 MJCF 模型随此仓库一起提供。
