ros2-mcp

ros2-mcp is an MCP (Model Context Protocol) server so AI agents (Grok, Cursor, Claude, …) can inspect and control ROS2 graphs — topics, nodes, services, TF, actions — without hand-writing every ros2 CLI call.

Product: mergeos-bounties/ros2-mcp

Install (one command)

Grok — recommended

pip install "git+https://github.com/mergeos-bounties/ros2-mcp.git" && grok plugin install mergeos-bounties/ros2-mcp --trust

This installs the Python CLI (ros2-mcp) and the Grok plugin (skill + MCP server from .mcp.json).

Check:

ros2-mcp version
ros2-mcp doctor
ros2-mcp demo
grok plugin list
grok mcp list

Local clone:

git clone https://github.com/mergeos-bounties/ros2-mcp.git
cd ros2-mcp
pip install -e ".[dev]"
grok plugin install . --trust

Other agents (stdio MCP)

After pip install "git+https://github.com/mergeos-bounties/ros2-mcp.git", point any MCP host at:

Claude Desktop — merge examples/claude_desktop_config.json into Claude MCP config.

Cursor — merge examples/cursor_mcp.json.

Grok config.toml (manual, without plugin):

[mcp_servers.ros2_mcp]
command = "ros2-mcp"
args = ["serve"]
env = { ROS2_MCP_MODE = "mock" }
enabled = true

One-liner via Grok CLI:

pip install "git+https://github.com/mergeos-bounties/ros2-mcp.git"
grok mcp add ros2-mcp -- ros2-mcp serve

Supported AI agents / hosts

All packages speak MCP over stdio (ros2-mcp serve). Default mode is mock (offline, no simulator/terminal/GIMP required).

Table of contents

• Modes
• Highlights
• Screenshots
• Quick start
• Tiếng Việt quickstart
• Docker image
• CLI reference
• MCP resources
• Logging
• MCP host config
• Diagrams
• Repository layout
• Development
• MergeOS bounties
• License

Modes

Live parameter listing is redacted by default: ros2_list_params returns
parameter names and value: "<redacted-live-value>" so MCP host transcripts
and CI logs do not accidentally capture runtime configuration. Use
ros2_get_param only when an explicit single live value read is intended.

Highlights

Screenshots

Mock graph	Pub + echo
Seeded graph / doctor	cmd_vel pub + pose echo

Quick start

cd ros2-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"

ros2-mcp version
ros2-mcp demo
ros2-mcp tools list

Mock mode needs no ROS2 install.

Tiếng Việt quickstart

ros2-mcp mặc định chạy ở mock mode, vì vậy bạn có thể thử ngay cả khi
máy chưa cài ROS2.

cd ros2-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

ros2-mcp version
ros2-mcp demo
ros2-mcp tools list

Khi muốn kết nối tới hệ ROS2 thật, hãy cài và source ROS2 trên máy host rồi đặt
mode sang live:

export ROS2_MCP_MODE=live
ros2-mcp doctor
ros2-mcp serve

Nếu chỉ cần kiểm tra nhanh, hãy giữ ROS2_MCP_MODE=mock để dùng đồ thị demo
turtlesim-like có sẵn.

Docker image

Build a ROS2 Humble image with ros2-mcp installed into an isolated Python
3.11 virtual environment:

docker build -t ros2-mcp:humble .

Run the offline mock demo:

docker run --rm ros2-mcp:humble demo

Serve MCP over stdio from the container:

docker run --rm -i ros2-mcp:humble serve

For live ROS2 graphs, run on the host network and switch to live mode:

docker run --rm -i --network host \
  -e ROS2_MCP_MODE=live \
  -e ROS_DOMAIN_ID="${ROS_DOMAIN_ID:-0}" \
  ros2-mcp:humble serve

The entrypoint sources /opt/ros/humble/setup.bash before invoking
ros2-mcp, so ROS2 CLI tools are available to live-mode backend calls.

CLI reference

# MCP for Cursor / Claude / Grok-compatible hosts
ros2-mcp serve

# With structured tool-call logging (JSON to stderr)
ros2-mcp serve --verbose

MCP resources

In addition to tools, the server exposes an MCP resource template so hosts can
read a topic snapshot as addressable content instead of calling a tool.

The snapshot is served by the active backend (mock or live), so it reflects the
same graph the ros2_* tools operate on. The leading slash is optional and
normalized internally (topic://clock and topic:///clock resolve to /clock).

// read: topic://clock
{
  "ok": true,
  "uri": "topic://clock",
  "topic": "/clock",
  "type": "rosgraph_msgs/msg/Clock",
  "publishers": ["/mock_clock"],
  "subscribers": [],
  "mode": "mock",
  "messages": [{ "stamp": 0.025, "data": { "sec": 0, "nanosec": 0 } }]
}

Note: the MCP SDK's URI-template matcher binds a single path segment, so a
namespaced topic containing / (e.g. /turtle1/pose) is fully supported when
the resource is invoked directly but cannot be addressed through a literal
topic:// URI read. Use ros2_topic_echo for namespaced topics via the host.

Logging

ros2-mcp serve emits structured JSON logs to stderr only. This is deliberate: the MCP stdio transport uses stdout for the JSON-RPC protocol stream, so any log written to stdout would corrupt the protocol and break the host connection. All logging goes to stderr, leaving stdout clean for MCP.

Each record is a single JSON line, easy to pipe into a log collector:

{"ts": 1712345678.9, "level": "DEBUG", "logger": "ros2_mcp", "msg": "tool_call", "tool": "ros2_list_topics", "duration_ms": 1.42, "status": "ok"}

Capture logs without touching the protocol stream by redirecting stderr:

ros2-mcp serve --verbose 2> ros2-mcp.log

MCP host config

Example stdio server entry (adjust path to your venv):

{
  "mcpServers": {
    "ros2-mcp": {
      "command": "ros2-mcp",
      "args": ["serve"],
      "env": {
        "ROS2_MCP_MODE": "mock"
      }
    }
  }
}

Set ROS2_MCP_MODE=live only on machines with a working ROS2 environment.

Diagrams

System architecture and workflow — full width. Open the HTML files for dark/light theme and export (PNG/SVG).

Architecture

Open interactive diagram

Workflow

Open interactive diagram

Generated with archify.

Repository layout

AI agent (MCP host)
        │ stdio
        ▼
   ros2-mcp server
        │
   ┌────┴────┐
   │ mock    │  seeded graph (CI / Windows)
   │ live    │  ros2 CLI subprocess bridge
   └─────────┘

src/ros2_mcp/
  cli.py
  backend/     # mock + live backends
  server.py    # FastMCP tools
docs/screenshots/
docs/diagrams/

Development

pytest -q
ruff check src tests
ros2-mcp demo

Live mode tests should mock subprocesses — CI must not require a ROS2 distro.

MergeOS bounties

Tools for actions/TF, live parsers, Lappa HTTP bridge, publish allowlists.
Star → claim → PR master → MRG 25–200. Evidence: CLI logs / MCP host config snippets (redact secrets).

License

MIT · MergeOS / ThanhTrucSolutions

Configuration

See MCP_HOST_CONFIG.md for Claude/Cursor setup.