UAV-MCP

CP > 🛺 MCP (Model Context Protocol) based intelligent UAV control server - plan flights, perceive environments, and generate executable code using natural language. [](https://www.python.org/) [](LICENSE) --- ## Project Overview UAV-MCP is a UAV control backend service running on the MCP protocol, allowing AI assistants (like Claude) to directly control a simulated UAV system through dialogue. Users don't need to write any code; they simply describe their flight intentions in natural language, and the system completes the entire process from command parsing, path planning, obstacle perception, visualization preview, to generating executable code. **Key Features:** - 🗣️ **Natural Language Driven**: Describe flight tasks directly in natural language, without needing to understand underlying interfaces. - 🧠 **AI-Driven Obstacle Avoidance**: Unlike traditional A* algorithms, this system uses guided AI to understand obstacle distributions and autonomously replans paths around obstacles. - 📷 **Image Recognition Modeling**: Upload real photos or route planning images, and AI automatically extracts obstacle coordinates or waypoints. - 🗺️ **3D Grid Space**: A 10×10×10 meter three-dimensional simulation environment, with the starting point at the center (5,5,0). - 💻 **Dual-Version Code Generation**: The same route simultaneously outputs simulation and DroneKit real hardware version Python code. --- ## Functional Architecture ``` Natural Language / Images ↓ AI Translation / Image Recognition ↓ Command Parsing & Path Planning ↓ Collision Detection → AI Replanning 3D Visualization & 2D Maps Generate Executable Code (Simulation / DroneKit) ``` --- ## Directory Structure ``` UAV-MCP/ ├── server.py # MCP server entry ├── config.py # Global parameter configuration ├── core/ # Core engine │ ├── grid_space.py # 3D grid space management │ ├── flight_planner.py # Path planning and collision detection │ └── command_parser.py # Natural language command parsing ├── ai/ # AI intelligence layer │ ├── translator.py # Natural language to action sequence converter ├── replanner.py # AI obstacle replanner ├── vision_recognizer.py # Grid map visual recognizer │ ├── image_flight_planner.py# Route image to action sequence planner │ └── real_image_recognizer.py# Real image obstacle recognizer ├── visualization/ # Visualization layer │ ├── visualizer_3d.py # 3D flight trajectory visualization │ ├── layer_visualizer.py # Layered 2D PNG map generation │ └── environment_visualizer.py # Independent 3D environment preview ├── codegen/ # Code generation layer │ ├── generator.py # Simulation code generator │ dronekit_generator.py # DroneKit real hardware code generator tools/ # MCP tool adapter layer │ └──.py # Spatial awareness tools └── missions/ # Mission script examples ├── simple_sim.py └──ission_dronekit.py--- ## Tool List Name | Function Description | |-----------|----------------------| | `ai_translate_flight` | Translates (e.g., zigzag, spiral, rectangle) into action sequences | | `ight_image_planner`izes waypoints in route planning images, generating flight action sequences `parse_command` | standard action commands (upforward/backward/left/right) | | `plan_flight` | Plans 3D routes based on action sequences, generating | | `ai_replan_with_obstacles` | Upon detecting obstacle collisions, AI replans paths around obstacles | | `generate_layer_maps` | Generates 2D PNG top-down maps for each height layer (for AI visual perception) | | `analyze_grid_space_vision` | AI visually recognizes UAV and obstacle coordinates in PNG maps | | `upload_map_image` | Uploads real environment photos; AI automatically identifies obstacles and converts them into grid coordinates | | `add_obstacles` | Manually adds obstacles to the grid space | | `clear_obstacles` | Clears all obstacles, resetting the environment | | `get_obstacles` | Retrieves all obstacle coordinates in the current environment | | `visualize_flight` | Real-time visualization of flight trajectories in a 3D window | | `visualize_grid_environment` | Independent preview of 3D grid environment (without waypoints) | | `generate_uav_code` | Generates executable UAV control code (simulation + DroneKit versions) | | `reset_position` | Resets UAV to initial position, clearing all waypoints | | `get_flight_info` | Retrieves detailed information about the current route | --- ## Quick Start ### 1. Environment Requirements - Python 3.10+ - MCP-compatible AI client (Claude Desktop recommended) ### 2. Install Dependencies ```bash pip install -r requirements.txt ``` or using `pyproject.toml`: ```bash pip install mcp numpy matplotlib Pillow ``` ### 3. Configure MCP Client Depending on the client used, select the corresponding configuration method: #### Method 1: Qoder IDE Locate and edit the MCP configuration file: ``` C:\Users\<YourUsername>\AppData\Roaming\Qoder\SharedClientCache\mcp.json ``` following content to ``: ```json "uav-mcp-server": { "timeout": 60 "type": "stdio", "command": "D:\\Anaconda3\\python.exe", "args": [ "i:\\UAV\\UAV-MCP\\server.py" ], "env": {}, disabled": false } **Note**: > - `command` should be the full path to your Python interpreter (Anaconda environment recommended) > - `args` should be the absolute path to `server.py` > - `disabled` must be `false` to take effect #### Method 2 Desktop Locate and edit: ``` C\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json ``` Add: ```json { "mcpServers": { "uav-mcp-server": { command": "D:\\3\\python.exe", "args": ["iAV\\UAV-MCP\\server.py"] } } ``` #### Method 3: Other MCP-compatible clients Configure stdio-type server with the command: ``` D:\An\python.exe i:\UAV\UAV-MCP\server.py ``` ### Verify Installation After modifying the configuration, restart the MCP client and input: ``` Get current ``` If location information (starting point 5,5,0) is returned, the connection is successful. --- ## Usage Examples ### Basic Flight Commands ``` User: Ascend 2 meters, move forward 5 meters, shift right 3 meters, descend 1AI → parse_command → plan_flight →ight ``` ### Natural Language Trajectory ``` User: Help me plan a zig trajectory AI →_flight → parse_command → plan_flight ``` ### Modeling ``` User: an indoor photo] in the room and plan a flight path AI → upload → add_obstacles → plan_flight → ai_replan_with_obstacles ``` ### Generate Real Hardware Code ``` User code that can run real UAV AI →av_code (outputs both simulation and DroneKit versions) ## Simulation Space Description | Parameter | Value | |-----------|| Space Size | 10×10×10 meters | | Coordinate Range | X: [0,10], Y: [0,10], Z: [0,10] | | Starting Position | (5, 5, 0) — bottom center of the map | | Movement Speed | 0.5 meters/second | | Hover Time | 2.0 seconds | | Coordinate Axis Direction | X→right, Y→forward, Z→up | --- ## Dependencies | Library | Purpose | |---------|---------| | `mcp >= 0.9.0` | MCP server protocol | | `numpy >= 1.20.0` | Numerical computation | | `matplotlib >= 3.3.0` | 2D/3D visualization | | `Pillow >= 8.0.0` | Image processing | | `scipy >= 1.6.0` | Scientific computing | --- ## Project Features ### AI-Driven Obstacle Avoidance Design Unlike traditional A* pathfinding, this project uses a **"guided guidance"** approach: when path collisions are detected, the system generates detailed descriptions of obstacle distributions, guiding AI to understand spatial relationships and output detour trajectories. This makes the system more flexible and capable of handling complex spatial reasoning tasks. Loading Strategy Heavyweight modules like Matplotlib are not loaded during MCP server startup (to avoid timeouts), only initialized tools are actually called, server responses. ### Dual-Version Code Generation The same set of waypoint data can simultaneously generate: - **Simulation Version**: uses `time.sleep()` to simulate flight timing, can run directly on any computer - **DroneKit Version**: connects to Pix controllers via MAVLink protocol controlling real hardware Contact Information - **GitHub**: [ATOI-Ming/UAV-MCP](github.com/ATOI/UAV-MCP) - **Email**: 175@qq.com - **WeChat**: flytoworldenddream --- ## License MIT License