Back to search
nav2_mcp_server
SkillGitHub
MCP server that provides tools and resources to control and monitor robots using Nav2.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/ajtudela--nav2-mcp-server)HTML
<a href="/listings/ajtudela--nav2-mcp-server"><img src="/api/listings/ajtudela--nav2-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
1. Copy the environment configuration template:
cp .env.example .env
2. 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
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 186 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # 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"
- }
- }
- ```
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.