# Ros2 Mcp

> ros2-mcp — MCP server for AI agents to inspect and control ROS2 (mock + live CLI bridge)

- **Type:** MCP server
- **Install:** `agentstack add mcp-mergeos-bounties-ros2-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [mergeos-bounties](https://agentstack.voostack.com/s/mergeos-bounties)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [mergeos-bounties](https://github.com/mergeos-bounties)
- **Source:** https://github.com/mergeos-bounties/ros2-mcp
- **Website:** https://mergeos.shop

## Install

```sh
agentstack add mcp-mergeos-bounties-ros2-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)](https://modelcontextprotocol.io) 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](https://github.com/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](https://github.com/mergeos-bounties/Lappa) package IDE workflows |

---

## Screenshots

| Mock graph | Pub + echo |
| :---: | :---: |
|  |  |
| *Seeded graph / doctor* | *cmd_vel pub + pose echo* |

---

## Quick start

```powershell
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 |

```powershell
# 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`).

```jsonc
// 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:

```json
{"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:

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

---

## MCP host config

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

```json
{
  "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](https://github.com/tt-a1i).*

---

## Repository layout

```text
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

```powershell
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](https://github.com/mergeos-bounties)
- **Source:** [mergeos-bounties/ros2-mcp](https://github.com/mergeos-bounties/ros2-mcp)
- **License:** MIT
- **Homepage:** https://mergeos.shop

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-mergeos-bounties-ros2-mcp
- Seller: https://agentstack.voostack.com/s/mergeos-bounties
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.