nav2_mcp_server

This MCP server exposes a set of Nav2 navigation controls and monitoring capabilities via the MCP protocol. It provides tools to command navigation to poses, follow waypoints, rotate the robot, manage costmaps, and interact with the Nav2 lifecycle. Typical usage is to connect a MCP client to the server and invoke the available tools described in the Tools section. The server supports asynchronous operations with progress feedback and cancellation, enabling responsive control of long-running tasks like path planning and execution. The environment variables allow configuring ROS 2 networking and transport behavior (stdio vs. http) to fit your deployment environment.

Prerequisites:

• ROS 2 (Jazzy) installed and sourced
• Python installed
• uv (Python package manager) installed
• Network configuration aligned with ROS 2 (domain IDs, hostnames)

Install with uv from the repository:

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 users can build or pull the image:

# Build the image
docker build -t nav2-mcp-server:latest .

# Or pull the latest
docker pull ghcr.io/ajtudela/nav2_mcp_server:latest

Running the server locally with uv:

uv run nav2_mcp_server

Note: If you plan to use the http transport, configure TRANSPORT_MODE and related HTTP_ variables as described in the Environment Variables section of the README.

Environment variables to consider:

• TRANSPORT_MODE: stdio (default) or http
• HTTP_HOST / HTTP_PORT: bind address and port when using http transport
• LOG_LEVEL: DEBUG, INFO, WARNING, ERROR, CRITICAL
• ROS_DOMAIN_ID and ROS_LOCALHOST_ONLY: ROS 2 networking controls

Common issues:

• Ensure ROS 2 environment is properly sourced and ROS_DOMAIN_ID matches between nodes.
• If using http transport, ensure the HTTP port is exposed and not blocked by a firewall.
• When running in Docker, pass through necessary ROS and network settings to the container.

Configuration tips:

• Use TRANSPORT_MODE=stdio for local development; switch to http for networked clients.
• Set ROS_DOMAIN_ID to a consistent value across nodes to avoid isolation issues.