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

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