robot-mcp-server

中文文档

A more complete robot-control MCP server for LLMs, agent systems, and automation platforms, with unified control for Unitree robots and DJI Tello drones.

What Was Improved

Compared with the original version, this project is now a more practical engineering baseline instead of a minimal prototype:

- Supports both mock and hardware backends so workflows can be validated without real devices
- Adds a unified configuration layer with environment-variable and CLI overrides
- Adds health checks, status inspection, capability discovery, and a global emergency-stop tool
- Adds built-in routine templates for common robot workflows
- Adds a lightweight sequence executor so clients can submit multiple built-in routines in one request
- Strengthens adapters with stricter parameter validation and connection-state protection
- Fixes missing dependency declarations, fragile startup flow, and unstable relative imports
- Adds unit tests and a local demo for easier verification and regression checks

Project Structure

.
├── examples/
│   └── demo.py
├── src/
│   ├── __init__.py
│   ├── config.py
│   ├── dji_adapter.py
│   ├── exceptions.py
│   ├── main.py
│   ├── service.py
│   └── unitree_adapter.py
├── tests/
│   └── test_service.py
├── README.md
├── README.zh-CN.md
├── requirements.txt
└── run.ps1

Installation

Requirements:

- Python 3.10+
- Windows PowerShell or any terminal that can run Python

Install dependencies:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

Included by default:

- mcp
- djitellopy

If you want to connect to real Unitree hardware, install the corresponding SDK as well:

python -m pip install git+https://github.com/unitreerobotics/unitree_sdk2_python.git

Quick Start

Recommended mock-mode startup:

.\run.ps1

or:

python -m src.main --backend mock --transport stdio

Start with HTTP transport:

.\run.ps1 -Backend mock -Transport streamable-http -Host 127.0.0.1 -Port 8000

Connect to real hardware:

python -m src.main --backend hardware --transport stdio

It is recommended to validate your workflow in mock mode before switching to hardware.

Environment Variables

| Variable | Default | Description |
| --- | --- | --- |
| ROBOT_MCP_BACKEND | mock | Backend mode: mock / hardware |
| ROBOT_MCP_TRANSPORT | stdio | Transport: stdio / streamable-http |
| ROBOT_MCP_HTTP_HOST | 127.0.0.1 | HTTP bind host |
| ROBOT_MCP_HTTP_PORT | 8000 | HTTP port |
| ROBOT_MCP_LOG_LEVEL | INFO | Log level |
| ROBOT_MCP_UNITREE_TIMEOUT_SECONDS | 10 | Unitree connection timeout |
| ROBOT_MCP_DEFAULT_TAKEOFF_HEIGHT | 1.2 | Default DJI takeoff height in meters |
| ROBOT_MCP_TELLO_HOST | empty | Specific Tello host |

Available MCP Tools

Shared tools:

- server_status
- list_robot_capabilities
- list_robot_routines
- run_routine_sequence
- health_check
- emergency_stop_all

Unitree tools:

- unitree_connect
- unitree_move(velocity, duration=1.0)
- unitree_stop
- unitree_status
- unitree_disconnect
- unitree_move_and_stop(velocity, duration=1.0)
- unitree_out_and_back(velocity, forward_duration=1.0, return_duration=None)
- unitree_pulse_patrol(velocity, pulse_duration=0.8, pause_duration=0.3, cycles=3)
- unitree_inspection_sweep(velocity=1.0, forward_duration=1.0, checkpoint_pause=0.5, cycles=2)

Notes:

- velocity range: -3.0 ~ 3.0 m/s
- duration range: 0.1 ~ 30.0 seconds

DJI tools:

- dji_connect
- dji_takeoff(height=None)
- dji_land
- dji_emergency_stop
- dji_status
- dji_disconnect
- dji_takeoff_hover_land(height=None, hover_seconds=3.0)
- dji_quick_observe(height=None, hover_seconds=5.0)
- dji_perimeter_scan(height=None, hover_seconds=2.0, checkpoints=3)

Notes:

- height range: 0.2 ~ 10.0 meters
- When height is omitted, the configured default is used

Built-in Routines

To save client-side development time, the server includes several composed actions:

- unitree_move_and_stop
Connects if needed, performs one move, and stops automatically
- unitree_out_and_back
Moves forward, returns, and stops for a simple round-trip patrol
- unitree_pulse_patrol
Repeats short move/pause cycles for lightweight patrol scenarios
- unitree_inspection_sweep
Runs a compact inspection routine with forward movement, checkpoint stop, and return movement
- dji_takeoff_hover_land
Takes off, hovers for a configurable duration, and lands automatically
- dji_quick_observe
A convenience observation routine with takeoff, hover, and landing
- dji_perimeter_scan
A lightweight aerial scan routine with multiple hover checkpoints

Sequence Executor

run_routine_sequence lets clients submit several built-in routines and pause steps in one request.

Example:

[
  {
    "action": "unitree_move_and_stop",
    "params": {
      "velocity": 1.0,
      "duration": 1.2
    }
  },
  {
    "action": "pause",
    "params": {
      "duration": 1
    }
  },
  {
    "action": "dji_takeoff_hover_land",
    "params": {
      "height": 1.5,
      "hover_seconds": 3
    }
  }
]

Supported sequence actions:

- pause
- unitree_move_and_stop
- unitree_out_and_back
- unitree_pulse_patrol
- unitree_inspection_sweep
- dji_takeoff_hover_land
- dji_quick_observe
- dji_perimeter_scan

Resources and Prompts

In addition to tools, the server also exposes:

- Resource: robot://status/summary
- Prompt: safe_operation_checklist(device)

Local Demo

python examples\demo.py

Tests

python -m unittest discover -s tests -v

Usage Tips

- Prefer mock mode during development
- Call health_check before connecting real hardware
- Inspect server_status before movement or takeoff commands
- Use emergency_stop_all first when something goes wrong

Known Limits

- Unitree hardware control is still a lightweight SDK integration layer intended as a starting point for extension
- Current tests mainly cover mock mode; real hardware behavior still needs on-site integration testing
- Exact streamable-http behavior depends on the installed mcp package version

License

MIT License