Ros2 Mcp

ros2-mcp

[](https://www.python.org/downloads/) [](pyproject.toml) [](LICENSE) [](https://modelcontextprotocol.io) [](https://github.com/mergeos-bounties)

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

---

Table of contents

• [Modes](#modes)
• [Highlights](#highlights)
• [Screenshots](#screenshots)
• [Quick start](#quick-start)
• [CLI reference](#cli-reference)
• [MCP resources](#mcp-resources)
• [Logging](#logging)
• [MCP host config](#mcp-host-config)
• [Diagrams](#diagrams)
• [Repository layout](#repository-layout)
• [Development](#development)
• [MergeOS bounties](#mergeos-bounties)
• [License](#license)

---

Modes

| Mode | When | Behavior | | --- | --- | --- | | mock (default) | Windows / CI / no ROS2 install | Seeded turtlesim-like graph: topics, pub, echo, services, TF, actions | | live | Host has ROS2 + CLI | Real graph via ros2 subprocess bridge (secrets redacted in logs) |

---

Highlights

| Capability | Description | | --- | --- | | Offline demo | ros2-mcp demo exercises doctor, topics, pub/echo, spawn, TF, actions | | MCP stdio serve | Plug into agent hosts as an MCP server | | One-shot call | ros2-mcp call without a full MCP host | | Tool list | Discover registered MCP tools | | Lappa-friendly | Complements Lappa package IDE workflows |

---

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.

---

CLI reference

| Command | Purpose | | --- | --- | | ros2-mcp version | Version + mode | | ros2-mcp demo | Offline smoke of core backend APIs | | ros2-mcp serve | MCP server over stdio (for hosts) | | ros2-mcp serve --verbose | Same, plus structured JSON tool-call logs on stderr | | ros2-mcp call … | One-shot tool call (mock/live) | | ros2-mcp tools list | List MCP tools |

# 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.

| URI | Returns | | --- | --- | | topic:// | JSON snapshot: type, publishers, subscribers, backend mode, and the last buffered messages (up to 5) for the topic |

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.

| Flag | Level | What you get | | --- | --- | --- | | ros2-mcp serve | INFO | Lifecycle only: one serve_start record (transport, mode, tool count, version) | | ros2-mcp serve --verbose (-v) | DEBUG | Per-tool-call records: tool_call_start, tool_call (with duration_ms, status), and tool_call_error (with traceback) on failure |

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](docs/diagrams/architecture.html)

Workflow

[Open interactive diagram](docs/diagrams/workflow.html)

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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: mergeos-bounties
• Source: mergeos-bounties/ros2-mcp
• License: MIT
• Homepage: https://mergeos.shop

Install and usage instructions live in the source repository linked above.