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" }

Or one-shot:

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
• Docker image
• CLI reference
• Lappa HTTP bridge tools
• MCP resources
• MCP host config
• Diagrams
• Repository layout
• Development
• MergeOS bounties
• License
• Configuration
• IDE Configuration

---

Modes

All packages ship with mock mode as the default.
Parameter names and value: "" so MCP host transcripts and CI logs do not accidentally capture runtime configuration. Use ROS2_MCP_MODE=live only when a live ROS2 graph is available.

---

Highlights

---

Quick start

git clone https://github.com/mergeos-bounties/ros2-mcp.git
cd ros2-mcp
pip install -e ".[dev]"
ros2-mcp version
ros2-mcp demo
ros2-mcp tools list

---

Docker image

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

docker build -t ros2-mcp:humble .
docker run --rm ros2-mcp:humble demo

Serve MCP over stdio from the container:

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

---

CLI reference

---

Lappa HTTP bridge tools

Issue #33 adds optional Lappa simulator HTTP bridge helpers while keeping the package safe for offline CI and MCP hosts. Configure a live bridge with:

export ROS2_MCP_LAPPA_URL=http://127.0.0.1:8765

Available tools:

CLI examples:

ros2-mcp call lappa_pose
ros2-mcp call lappa_cmd_vel linear_x=0.3 angular_z=0.1

Both commands avoid secrets and only use a local/user-configured base URL.

---

MCP resources

In addition to tools, the server exposes an MCP resource template so hosts can inspect the ROS2 graph structure.

Note: the MCP SDK’s URI-template matcher binds a single path segment, so a ros2-mcp serve emits structured JSON logs to stderr only. 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.

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

To capture logs to a file:

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

---

MCP host config

{
  "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

Architecture

Workflow

---

Repository layout

ros2-mcp/
├── src/ros2_mcp/
│   ├── __init__.py
│   ├── server.py          # FastMCP tools
│   ├── mock_backend.py    # Mock ROS2 graph
│   └── live_backend.py    # Live ROS2 graph
├── tests/
├── docs/
├── examples/
├── scripts/
├── .mcp.json
└── pyproject.toml

---

Development

git clone https://github.com/mergeos-bounties/ros2-mcp.git
cd ros2-mcp
pip install -e ".[dev]"
pytest -q
ruff check src/
ros2-mcp demo

---

MergeOS bounties

Star → claim → PR master → MRG 25–200. Evidence: CLI logs / MCP host config snippets (redact secrets).

---

License

MIT

---

Configuration

See MCP_HOST_CONFIG.md for Claude/Cursor setup.

---

IDE Configuration

• Cursor MCP Config — Copy-paste configuration for Cursor IDE with mock/live modes
• Live vs Mock Safety Matrix — Safety considerations for live vs mock modes