Nav2 MCP Server

ROS2 License Build Docker image Python Dynamic TOML Badge codecov

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.

Demo of Nav2 MCP Server

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:
cp .env.example .env
  1. 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

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"
  }
}