nav2_mcp_server by ajtudela - MCP Server

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

Copy the environment configuration template:

cp .env.example .env

Edit .env to customize settings:

# 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: Middleware for robotics (Jazzy)
fastmcp: MCP server framework
python: Python programming language
uv: Python package manager (optional)

Install with uv

Clone the repository and install with uv:

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:

uv add git+https://github.com/ajtudela/nav2_mcp_server.git

Docker

Build the image

Build the image:

docker build -t nav2-mcp-server:latest .

Pull the image

Pull the latest image from the Docker registry:

docker pull ghcr.io/ajtudela/nav2_mcp_server:latest

Usage

Running with uv

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)

{
  "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)

"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

"nav2 mcp server": {
  "type": "http",
  "url": "http://localhost:3001/mcp",
  "env": {
    "TRANSPORT_MODE": "http",
    "LOG_LEVEL": "INFO"
  }
}