Skip to content
Back to search

nav2_mcp_server

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ajtudela--nav2-mcp-server/badge.svg)](/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)

  1. # Nav2 MCP Server
  2. ![ROS2](https://img.shields.io/badge/ros2-jazzy-blue?logo=ros&logoColor=white)
  3. ![License](https://img.shields.io/github/license/ajtudela/nav2_mcp_server)
  4. [![Build](https://github.com/ajtudela/nav2_mcp_server/actions/workflows/python-package.yml/badge.svg?branch=main)](https://github.com/ajtudela/nav2_mcp_server/actions/workflows/python-package.yml)
  5. [![Docker image](https://github.com/ajtudela/nav2_mcp_server/actions/workflows/docker_image.yml/badge.svg?branch=main)](https://github.com/ajtudela/nav2_mcp_server/actions/workflows/docker_image.yml)
  6. ![Python](https://img.shields.io/python/required-version-toml?tomlFilePath=https%3A%2F%2Fraw.githubusercontent.com%2Fajtudela%2Fnav2_mcp_server%2Frefs%2Fheads%2Fmain%2Fpyproject.toml)
  7. ![Dynamic TOML Badge](https://img.shields.io/badge/dynamic/toml?url=https%3A%2F%2Fraw.githubusercontent.com%2Fajtudela%2Fnav2_mcp_server%2Frefs%2Fheads%2Fmain%2Fpyproject.toml&query=%24.project.dependencies%5B2%5D&label=dependency)
  8. [![codecov](https://codecov.io/gh/ajtudela/nav2_mcp_server/graph/badge.svg?token=munojKDLxe)](https://codecov.io/gh/ajtudela/nav2_mcp_server)
  9. 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.
  10. ![Demo of Nav2 MCP Server](docs/demo.gif)
  11. ## Features
  12. * **Navigation control**: Navigate to specific poses, follow waypoint sequences, and execute precise robot movements
  13. * **Real-time status**: Monitor navigation progress, robot pose, and system status with comprehensive feedback
  14. * **Costmap management**: Clear stale obstacle data and manage navigation costmaps for optimal path planning
  15. * **Lifecycle management**: Control Nav2 system startup and shutdown for complete system control
  16. * **ROS 2 integration**: Full compatibility with Nav2 navigation stack and ROS 2 ecosystem
  17. * **Async operations**: Non-blocking navigation commands with progress monitoring and cancellation support
  18. ## Tools
  19. | Tool | Description | Parameters |
  20. | ----------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
  21. | **navigate_to_pose** | Navigate the robot to a specific pose (position and orientation) in the map frame | `x: float, y: float, yaw: float` |
  22. | **follow_waypoints** | Navigate the robot through a sequence of waypoints in order | `waypoints: str (JSON array)` |
  23. | **spin_robot** | Rotate the robot in place by a specified angle | `angle: float` |
  24. | **backup_robot** | Move the robot backward by a specified distance | `distance: float, speed: float` |
  25. | **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` |
  26. | **undock_robot** | Undock the robot from a charging station or dock | `dock_type: str` |
  27. | **clear_costmaps** | Clear robot navigation costmaps to remove stale obstacle data | `costmap_type: str` |
  28. | **get_robot_pose** | Get the current position and orientation of the robot | — |
  29. | **cancel_navigation** | Cancel the currently active navigation task | — |
  30. | **nav2_lifecycle** | Control Nav2 lifecycle (startup or shutdown) | `action: str` |
  31. | **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` |
  32. | **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` |
  33. ## Environment Variables
  34. | Variable | Default | Description |
  35. | -------------------- | ------- | ------------------------------------------------------------ |
  36. | `ROS_DOMAIN_ID` | — | ROS 2 domain ID for network isolation (recommended to set) |
  37. | `ROS_LOCALHOST_ONLY` | — | Set to '1' to restrict ROS 2 communication to localhost only |
  38. ## Configuration
  39. ### Environment Variables
  40. | Variable | Default | Description |
  41. | -------------------- | --------- | --------------------------------------------------------------- |
  42. | `TRANSPORT_MODE` | `stdio` | Transport mode: `stdio` (local integration) or `http` (network) |
  43. | `HTTP_HOST` | `0.0.0.0` | HTTP host binding (only used when `TRANSPORT_MODE=http`) |
  44. | `HTTP_PORT` | `3001` | HTTP port (only used when `TRANSPORT_MODE=http`) |
  45. | `LOG_LEVEL` | `INFO` | Logging level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
  46. | `ROS_DOMAIN_ID` | — | ROS 2 domain ID for network isolation (recommended) |
  47. | `ROS_LOCALHOST_ONLY` | — | Set to '1' to restrict ROS 2 communication to localhost only |
  48. ### Setup
  49. 1. Copy the environment configuration template:
  50. ```bash
  51. cp .env.example .env
  52. ```
  53. 2. Edit `.env` to customize settings:
  54. ```bash
  55. # Transport mode: 'stdio' for local, 'http' for containerized/network
  56. TRANSPORT_MODE=stdio
  57. # HTTP settings (only needed if using http transport)
  58. HTTP_HOST=0.0.0.0
  59. HTTP_PORT=3001
  60. # Logging
  61. LOG_LEVEL=INFO
  62. ```
  63. ## Installation
  64. ### Dependencies
  65. - [Robot Operating System (ROS) 2](https://docs.ros.org/en/jazzy/): Middleware for robotics (Jazzy)
  66. - [fastmcp](https://github.com/jlowin/fastmcp): MCP server framework
  67. - [python](https://www.python.org/): Python programming language
  68. - [uv](https://github.com/astral-sh/uv): Python package manager (optional)
  69. ### Install with uv
  70. Clone the repository and install with uv:
  71. ```bash
  72. git clone https://github.com/ajtudela/nav2_mcp_server.git
  73. cd nav2_mcp_server
  74. # Set up ROS 2 environment variables if needed
  75. export ROS_DOMAIN_ID=0
  76. uv sync
  77. ```
  78. Or install directly from the repository:
  79. ```bash
  80. uv add git+https://github.com/ajtudela/nav2_mcp_server.git
  81. ```
  82. ### Docker
  83. #### Build the image
  84. Build the image:
  85. ```bash
  86. docker build -t nav2-mcp-server:latest .
  87. ```
  88. #### Pull the image
  89. Pull the latest image from the Docker registry:
  90. ```bash
  91. docker pull ghcr.io/ajtudela/nav2_mcp_server:latest
  92. ```
  93. ## Usage
  94. ### Running with uv
  95. ```bash
  96. uv run nav2_mcp_server
  97. ```
  98. ### Configuration example for Claude Desktop/Cursor/VSCode
  99. Add this configuration to your application's settings (mcp.json):
  100. #### Using uv (stdio transport)
  101. ```json
  102. {
  103. "nav2 mcp server": {
  104. "type": "stdio",
  105. "command": "uv",
  106. "args": [
  107. "run",
  108. "--directory",
  109. "/path/to/nav2_mcp_server",
  110. "nav2-mcp-server"
  111. ],
  112. "env": {
  113. "ROS_DOMAIN_ID": "0",
  114. "ROS_LOCALHOST_ONLY": "1"
  115. }
  116. }
  117. }
  118. ```
  119. #### Using Docker (stdio transport)
  120. ```json
  121. "nav2 mcp server": {
  122. "type": "stdio",
  123. "command": "docker",
  124. "args": [
  125. "run",
  126. "-i",
  127. "--rm",
  128. "ghcr.io/ajtudela/nav2_mcp_server"
  129. ],
  130. "env": {
  131. "ROS_DOMAIN_ID": "0",
  132. "ROS_LOCALHOST_ONLY": "1"
  133. }
  134. }
  135. ```
  136. #### Using HTTP transport
  137. ```json
  138. "nav2 mcp server": {
  139. "type": "http",
  140. "url": "http://localhost:3001/mcp",
  141. "env": {
  142. "TRANSPORT_MODE": "http",
  143. "LOG_LEVEL": "INFO"
  144. }
  145. }
  146. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.