Content
# Nav2 MCP Server
[](https://github.com/ajtudela/nav2_mcp_server/actions/workflows/python-package.yml)
[](https://github.com/ajtudela/nav2_mcp_server/actions/workflows/docker_image.yml)
[](https://codecov.io/gh/ajtudela/nav2_mcp_server)
An MCP (Model Context Protocol) server that provides tools and resources to control and monitor Nav2 navigation operations, allowing seamless integration with Nav2-enabled robots through the MCP protocol.
## Features
* **Navigation control**: Navigate to specific poses, follow waypoint sequences, and execute precise robot movements
* **Real-time status**: Monitor navigation progress, robot pose, and system status with comprehensive feedback
* **Costmap management**: Clear stale obstacle data and manage navigation costmaps for optimal path planning
* **Lifecycle management**: Control Nav2 system startup and shutdown for complete system control
* **ROS 2 integration**: Full compatibility with Nav2 navigation stack and ROS 2 ecosystem
* **Async operations**: Non-blocking navigation commands with progress monitoring and cancellation support
## Tools
| Tool | Description | Parameters |
| ----------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **navigate_to_pose** | Navigate the robot to a specific pose (position and orientation) in the map frame | `x: float, y: float, yaw: float` |
| **follow_waypoints** | Navigate the robot through a sequence of waypoints in order | `waypoints: str (JSON array)` |
| **spin_robot** | Rotate the robot in place by a specified angle | `angle: float` |
| **backup_robot** | Move the robot backward by a specified distance | `distance: float, speed: float` |
| **dock_robot** | Dock the robot to a charging station or dock | `x: float, y: float, yaw: float, dock_id: str, dock_type: str, nav_to_dock: bool` |
| **undock_robot** | Undock the robot from a charging station or dock | `dock_type: str` |
| **clear_costmaps** | Clear robot navigation costmaps to remove stale obstacle data | `costmap_type: str` |
| **get_robot_pose** | Get the current position and orientation of the robot | — |
| **cancel_navigation** | Cancel the currently active navigation task | — |
| **nav2_lifecycle** | Control Nav2 lifecycle (startup or shutdown) | `action: str` |
| **get_path** | Compute a navigation path between two poses | `start_x: float, start_y: float, start_yaw: float, goal_x: float, goal_y: float, goal_yaw: float, planner_id: str` |
| **get_path_from_robot** | Compute a navigation path from the robot's current pose to a goal pose | `goal_x: float, goal_y: float, goal_yaw: float, planner_id: str` |
## Environment Variables
| Variable | Default | Description |
| -------------------- | ------- | ------------------------------------------------------------ |
| `ROS_DOMAIN_ID` | — | ROS 2 domain ID for network isolation (recommended to set) |
| `ROS_LOCALHOST_ONLY` | — | Set to '1' to restrict ROS 2 communication to localhost only |
## Configuration
### Environment Variables
| Variable | Default | Description |
| -------------------- | --------- | --------------------------------------------------------------- |
| `TRANSPORT_MODE` | `stdio` | Transport mode: `stdio` (local integration) or `http` (network) |
| `HTTP_HOST` | `0.0.0.0` | HTTP host binding (only used when `TRANSPORT_MODE=http`) |
| `HTTP_PORT` | `3001` | HTTP port (only used when `TRANSPORT_MODE=http`) |
| `LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
| `ROS_DOMAIN_ID` | — | ROS 2 domain ID for network isolation (recommended) |
| `ROS_LOCALHOST_ONLY` | — | Set to '1' to restrict ROS 2 communication to localhost only |
### Setup
1. Copy the environment configuration template:
```bash
cp .env.example .env
```
2. Edit `.env` to customize settings:
```bash
# Transport mode: 'stdio' for local, 'http' for containerized/network
TRANSPORT_MODE=stdio
# HTTP settings (only needed if using http transport)
HTTP_HOST=0.0.0.0
HTTP_PORT=3001
# Logging
LOG_LEVEL=INFO
```
## Installation
### Dependencies
- [Robot Operating System (ROS) 2](https://docs.ros.org/en/jazzy/): Middleware for robotics (Jazzy)
- [fastmcp](https://github.com/jlowin/fastmcp): MCP server framework
- [python](https://www.python.org/): Python programming language
- [uv](https://github.com/astral-sh/uv): Python package manager (optional)
### Install with uv
Clone the repository and install with uv:
```bash
git clone https://github.com/ajtudela/nav2_mcp_server.git
cd nav2_mcp_server
# Set up ROS 2 environment variables if needed
export ROS_DOMAIN_ID=0
uv sync
```
Or install directly from the repository:
```bash
uv add git+https://github.com/ajtudela/nav2_mcp_server.git
```
### Docker
#### Build the image
Build the image:
```bash
docker build -t nav2-mcp-server:latest .
```
#### Pull the image
Pull the latest image from the Docker registry:
```bash
docker pull ghcr.io/ajtudela/nav2_mcp_server:latest
```
## Usage
### Running with uv
```bash
uv run nav2_mcp_server
```
### Configuration example for Claude Desktop/Cursor/VSCode
Add this configuration to your application's settings (mcp.json):
#### Using uv (stdio transport)
```json
{
"nav2 mcp server": {
"type": "stdio",
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/nav2_mcp_server",
"nav2-mcp-server"
],
"env": {
"ROS_DOMAIN_ID": "0",
"ROS_LOCALHOST_ONLY": "1"
}
}
}
```
#### Using Docker (stdio transport)
```json
"nav2 mcp server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"ghcr.io/ajtudela/nav2_mcp_server"
],
"env": {
"ROS_DOMAIN_ID": "0",
"ROS_LOCALHOST_ONLY": "1"
}
}
```
#### Using HTTP transport
```json
"nav2 mcp server": {
"type": "http",
"url": "http://localhost:3001/mcp",
"env": {
"TRANSPORT_MODE": "http",
"LOG_LEVEL": "INFO"
}
}
```
