rviz-mcp

rviz-mcp is an MCP server so AI agents can control RViz2 displays, fixed frames, and views — with a full offline mock for CI and demos (no ROS/RViz install required).

Product: mergeos-bounties/rviz-mcp

---

Install (one command)

Grok — recommended

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

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

Check:

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

Local clone:

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

Other agents (stdio MCP)

After pip install "git+https://github.com/mergeos-bounties/rviz-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.rviz_mcp]
command = "rviz-mcp"
args = ["serve"]
env = { RVIZ_MCP_MODE = "mock" }
enabled = true

One-liner via Grok CLI:

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

Supported AI agents / hosts

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

---

Highlights

---

Quick start

cd rviz-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
rviz-mcp demo
rviz-mcp demo --profile nav
rviz-mcp doctor
rviz-mcp status
pytest -q

rviz-mcp serve

---

Modes

---

Tools

---

Mock display graph quickstart

Run a full mock RViz2 display tree without RViz2 installed — useful for CI, documentation screenshots, and agent demos.

# 1. Seed the default display tree (Grid + TF + RobotModel)
rviz-mcp demo

# 2. Inspect the mock config
rviz-mcp status --json

# 3. Export the full config snapshot for agents
rviz-mcp export-config

# 4. Run against the MCP server (Cursor / Claude / Grok)
rviz-mcp serve
# Then query the rviz://config resource

# Non-PowerShell (bash / zsh)
python -m rviz_mcp demo
python -m rviz_mcp status --json
python -m rviz_mcp export-config
python -m rviz_mcp serve

The display graph includes class names, topics, and enable state — every field an agent needs to understand or replicate the layout.

---

Demo profiles

The default mock seed includes Grid, TF, and RobotModel. The navigation profile adds Map, LaserScan, and GlobalPath displays for nav-stack demos:

rviz-mcp demo --profile nav

---

Resources

Example payload:

{
  "ok": true,
  "mode": "mock",
  "fixed_frame": "map",
  "view": { "class": "rviz_default_plugins/Orbit", "distance": 10.0 },
  "displays": [
    { "name": "Grid", "class": "rviz_default_plugins/Grid", "enabled": true, "topic": "" }
  ],
  "display_count": 3,
  "panels": [
    { "class": "rviz_common/Displays", "name": "Displays", "dock": "left", "visible": true },
    { "class": "rviz_common/Views", "name": "Views", "dock": "right", "visible": true },
    { "class": "rviz_common/Time", "name": "Time", "dock": "bottom", "visible": true }
  ],
  "config_path": "mock://default.rviz"
}

---

Examples

• examples/cursor_mcp.json
• examples/claude_desktop_config.json
• docs/LIVE_BRIDGE.md for live bridge load_config and screenshot endpoints

---

Development

ruff check src tests
pytest -q
rviz-mcp tools list

---

MergeOS bounties

Star → claim issue → PR to master → MRG 25–200.
See mergeos.

---

License

MIT · MergeOS / ThanhTrucSolutions