Tello Drone MCP Server

A Model Context Protocol (MCP) server implementation for controlling the DJI Tello drone. This server allows any MCP-compatible client to control a Tello drone through a standardized interface.

This is under active development, read security considerations

Features

MCP Support
Real-time drone control through SSE (Server-Sent Events)
Robust error handling and logging
CORS-enabled for web clients (like mcp inspector)
Supports basic Tello drone commands:
- Takeoff
- Land
- Move (up/down/left/right/forward/back)
- Rotate (clockwise/counter-clockwise)

Prerequisites

Python 3.7+
DJI Tello drone
Network connection to the Tello drone
Root/sudo access (required for UDP socket binding)

Installation

Clone this repository:

git clone <repository-url>
cd drone-mcp

Install dependencies:

pip install -r requirements.txt

MCP Configuration

To enable your MCP client to connect to the Tello drone server, add the following configuration to your mcp.json file (usually located at ~/.cursor/mcp.json or in your project directory):

{
  "tello-drone": {
    "url": "http://localhost:3000/sse"
  }
}

This configuration allows MCP-enabled tools and models to automatically discover and connect to your Tello drone server.

Usage

Connect to your Tello drone's WiFi network (usually starts with "TELLO-").
Start the MCP server:

sudo python tello_mcp.py

The server will:

Initialize connection with the Tello drone
Start the MCP server on http://0.0.0.0:3000
Set up SSE endpoint at /sse
Handle messages at /message

Ensure the server is running before you plan to use it in your client (cursor, windsurf, code).

Available Tools

The server provides the following MCP tools:

1. Takeoff

{
    "name": "takeoff",
    "description": "Commands the Tello drone to take off",
    "inputSchema": {
        "type": "object",
        "properties": {}
    }
}

2. Land

{
    "name": "land",
    "description": "Commands the Tello drone to land",
    "inputSchema": {
        "type": "object",
        "properties": {}
    }
}

3. Move

{
    "name": "move",
    "description": "Moves the Tello drone in a specified direction",
    "inputSchema": {
        "type": "object",
        "properties": {
            "direction": {
                "type": "string",
                "enum": ["up", "down", "left", "right", "forward", "back"]
            },
            "distance": {
                "type": "integer",
                "minimum": 20,
                "maximum": 500
            }
        },
        "required": ["direction", "distance"]
    }
}

4. Rotate

{
    "name": "rotate",
    "description": "Rotates the Tello drone clockwise or counter-clockwise",
    "inputSchema": {
        "type": "object",
        "properties": {
            "direction": {
                "type": "string",
                "enum": ["cw", "ccw"]
            },
            "degrees": {
                "type": "integer",
                "minimum": 1,
                "maximum": 3600
            }
        },
        "required": ["direction", "degrees"]
    }
}

MCP Client Integration

To connect an MCP client:

Start your server and Connect to the SSE endpoint:

GET http://localhost:3000/sse

Prompt your MCP enabled model, which will communicate via SSE

event: endpoint
data: /message?sessionId=<session-id>

Send initialize request:

{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize"
}

List available tools:

{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "listTools"
}

Call a tool (example - takeoff):

{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "callTool",
    "params": {
        "name": "takeoff",
        "arguments": {}
    }
}

Error Handling

The server implements comprehensive error handling:

Drone connection failures
Invalid commands
Network timeouts
Protocol errors
Invalid tool parameters

All errors are logged and returned as proper JSON-RPC 2.0 error responses.

Logging

The server logs to stderr with detailed information about:

Server startup/shutdown
Drone connection status
Command execution
Client connections
Error conditions

Security Considerations

The server requires root/sudo access to bind to UDP ports
No authentication is implemented (rely on network security)
CORS is enabled for all origins (*)
Use in a controlled environment only

Development

The server is built using:

Python's mcp library for protocol handling
Starlette for HTTP/SSE transport
Uvicorn as the ASGI server
Native Python socket library for drone UDP communication

Troubleshooting

Server won't start:
- Ensure you have sudo/root access
- Check if the Tello's WiFi is connected
- Verify no other process is using port 3000
Drone won't connect:
- Ensure drone is powered on
- Check WiFi connection
- Verify no other application is controlling the drone
Commands fail:
- Check drone battery level
- Ensure drone is in a safe flying environment
- Verify command parameters are within allowed ranges

License

MIT

Contributing

Welcome to contribute.