gazebo-mcp

gazebo-mcp is an MCP server so AI agents can drive Gazebo / gz-sim: worlds, models, poses, pause/step — with a full offline mock for CI and demos (no Gazebo install required).

Product: mergeos-bounties/gazebo-mcp

Install (one command)

Grok — recommended

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

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

Check:

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

Local clone:

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

Other agents (stdio MCP)

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

One-liner via Grok CLI:

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

Related MCP server: rviz-mcp

Supported AI agents / hosts

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

Highlights

Quick start

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

gazebo-mcp serve

Docker mock image

Build a slim container that runs the MCP server in offline mock mode:

docker build -t gazebo-mcp:mock .

Run the server over stdio:

docker run --rm -i -e GAZEBO_MCP_MODE=mock gazebo-mcp:mock

Use Docker Compose for host integrations that expect a long-running stdio process:

docker compose up --build gazebo-mcp

Offline smoke check without privileged host Gazebo:

docker run --rm -e GAZEBO_MCP_MODE=mock gazebo-mcp:mock gazebo-mcp demo

The image installs only the Python package and its dependencies. It does not install Gazebo, mount host devices, or require privileged container settings.

Modes

Live mode can restrict spawn model types before reaching the bridge:

$env:GAZEBO_MCP_SPAWN_ALLOWLIST = "box,sphere,cylinder"

Tools

Velocity metadata

Mock pose updates can store linear and angular velocity metadata alongside the pose. The metadata is returned by gazebo_get_pose, gazebo_list_models, and gazebo://world snapshots:

gazebo-mcp call set_pose name=box_1 x=1 y=2 z=0.5 yaw=0.25 linear_x=0.2 angular_z=0.1

Demo profiles

The default mock seed includes a ground plane, box, and sphere. The fleet profile seeds ground_plane plus robot_0, robot_1, and robot_2 with distinct poses for multi-robot demos:

gazebo-mcp demo --profile fleet

Resources

The gazebo://world resource returns the live mock world state (or the live-bridge state in live mode). Example payload:

{
  "ok": true,
  "world": "shapes_demo",
  "paused": false,
  "sim_time_sec": 1.234,
  "model_count": 3,
  "models": [
    {"name": "ground_plane", "type": "plane", "pose": {"x": 0.0, "y": 0.0, "z": 0.0, "yaw": 0.0}},
    {"name": "box_1", "type": "box", "pose": {"x": 1.0, "y": 0.0, "z": 0.5, "yaw": 0.0}},
    {"name": "sphere_1", "type": "sphere", "pose": {"x": -1.0, "y": 0.5, "z": 0.5, "yaw": 0.0}}
  ],
  "physics": {
    "engine": "ode-mock",
    "max_step_size": 0.001,
    "real_time_factor": 1.0,
    "gravity": {"x": 0.0, "y": 0.0, "z": -9.8}
  }
}

Smoke it offline via the CLI:

gazebo-mcp call snapshot

One-shot calls can read tool arguments from a JSON object file:

{
  "name": "json_box",
  "model_type": "box",
  "x": 2,
  "y": 3,
  "z": 0.5
}

gazebo-mcp call spawn --json-file args.json

Examples

• examples/cursor_mcp.json

• examples/claude_desktop_config.json

• docs/HOST_SETUP.md for Cursor, Claude Desktop, and Grok setup

• docs/LIVE_BRIDGE.md for the live bridge health/world_info contract

Development

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

MergeOS bounties

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

License

MIT · MergeOS / ThanhTrucSolutions