Rviz Mcp

rviz-mcp

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

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:

| Field | Value | | --- | --- | | command | rviz-mcp | | args | ["serve"] | | env | RVIZ_MCP_MODE=mock |

Claude Desktop — merge [examples/claudedesktopconfig.json](examples/claudedesktopconfig.json) into Claude MCP config.

Cursor — merge [examples/cursormcp.json](examples/cursormcp.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

| Host | Support | Install | | --- | --- | --- | | Grok (CLI / TUI / Build) | Yes | grok plugin install mergeos-bounties/rviz-mcp --trust then pip install "git+https://github.com/mergeos-bounties/rviz-mcp.git" | | Claude Desktop | Yes | Copy [examples/claudedesktopconfig.json](examples/claudedesktopconfig.json) into Claude MCP settings | | Cursor | Yes | Merge [examples/cursormcp.json](examples/cursormcp.json) into Cursor MCP config | | Claude Code | Yes | stdio MCP: same command/args as Claude Desktop / Grok | | VS Code (MCP / Continue / Cline) | Yes | Generic stdio server config pointing at rviz-mcp serve | | Windsurf / Cascade | Yes | stdio MCP entry with rviz-mcp + serve | | Codex CLI | Yes (stdio) | Register MCP server command rviz-mcp serve in Codex MCP settings | | ChatGPT Desktop | Partial | Only if host supports custom MCP stdio servers | | Gemini CLI | Partial | Only if MCP stdio plugins are enabled |

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

---

Highlights

| Capability | Description | | --- | --- | | Offline mock | Display tree, fixed frame, view controller | | Live bridge | Optional HTTP/file bridge when RVIZ_MCP_MODE=live | | MCP stdio | Cursor / Claude / Grok host integration | | CLI | status · demo · doctor · serve · call |

---

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

| Mode | Env | Behavior | | --- | --- | --- | | mock (default) | RVIZ_MCP_MODE=mock | In-memory RViz config | | live | RVIZ_MCP_MODE=live + bridge URL/file | Forwards to local RViz bridge |

---

Tools

| Tool | Purpose | | --- | --- | | rviz_doctor | Connectivity / config health | | status (CLI) | Fixed frame, display count, mode, version (--json supported) | | rviz_seed_demo | Reset mock displays (Grid, TF, RobotModel) | | rviz_list_displays | Current display tree | | rviz_add_display / rviz_remove_display | Manage displays | | rviz_list_panels | Current panel layout | | rviz_add_panel / rviz_remove_panel | Manage mock UI panels | | rviz_set_fixed_frame | Fixed frame (e.g. map, odom) | | rviz_set_view | View controller type + look-at | | rviz_load_config / rviz_save_config | Config path (mock records path) | | rviz_screenshot | Mock screenshot path |

---

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

| URI | Purpose | | --- | --- | | rviz://config | Read-only snapshot of the current config: fixed_frame, view, displays (with display_count), panels, and config_path. Served from the mock display tree offline. |

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/cursormcp.json](examples/cursormcp.json)
• [examples/claudedesktopconfig.json](examples/claudedesktopconfig.json)
• [docs/LIVEBRIDGE.md](docs/LIVEBRIDGE.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

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/rviz-mcp
• License: MIT
• Homepage: https://mergeos.shop

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