Rviz

Python 3.11+ Version License: MIT MCP MergeOS

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/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

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/claude_desktop_config.json into Claude MCP settings
Cursor	Yes	Merge examples/cursor_mcp.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/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