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.

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

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

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 (recommended)

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

Install with pip

Install the package in development mode:

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
python3 -m pip install .

Or install directly from the repository:

python3 -m pip install 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

Running with pip installation

python3 -m nav2_mcp_server

Configuration example for Claude Desktop/Cursor/VSCode

Add this configuration to your application's settings (mcp.json):

Using uv (recommended)

{
  "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 pip installation

{
  "nav2 mcp server": {
    "type": "stdio",
    "command": "python3",
    "args": [
      "-m",
      "nav2_mcp_server"
    ],
    "env": {
      "ROS_DOMAIN_ID": "0",
      "ROS_LOCALHOST_ONLY": "1"
    }
  }
}

Using Docker

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