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