# rviz-mcp

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/)
[![Version](https://img.shields.io/badge/version-0.1.0-0E8A16.svg)](pyproject.toml)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-5319E7.svg)](https://modelcontextprotocol.io)
[![MergeOS](https://img.shields.io/badge/MergeOS-bounties-5319E7.svg)](https://github.com/mergeos-bounties)

**rviz-mcp** is an [MCP](https://modelcontextprotocol.io) 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](https://github.com/mergeos-bounties/rviz-mcp)

---

## Install (one command)

### Grok — recommended

```bash
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:

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

Local clone:

```bash
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](examples/claude_desktop_config.json) into Claude MCP config.

**Cursor** — merge [examples/cursor_mcp.json](examples/cursor_mcp.json).

**Grok config.toml** (manual, without plugin):

```toml
[mcp_servers.rviz_mcp]
command = "rviz-mcp"
args = ["serve"]
env = { RVIZ_MCP_MODE = "mock" }
enabled = true
```

**One-liner via Grok CLI:**

```bash
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](examples/claude_desktop_config.json) into Claude MCP settings |
| **Cursor** | **Yes** | Merge [examples/cursor_mcp.json](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

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

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

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

```bash
# 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:

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

```json
{
  "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/cursor_mcp.json)
- [examples/claude_desktop_config.json](examples/claude_desktop_config.json)
- [docs/LIVE_BRIDGE.md](docs/LIVE_BRIDGE.md) for live bridge load_config and screenshot endpoints

---

## Development

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

---

## MergeOS bounties

Star → claim issue → PR to **master** → MRG **25–200**.  
See [mergeos](https://github.com/mergeos-bounties/mergeos).

---

## License

MIT · MergeOS / ThanhTrucSolutions