UniRoboSim MCP

English | 简体中文

unirobosim-mcp exposes UniRoboSim evidence, simulation state, backend camera images, and explicitly enabled simulation control to MCP-compatible clients. The server has two deployment profiles:

• Evidence profile (default): bounded, read-only access to an operator-selected evidence root.

• Control profile (explicit): Evidence tools plus Read and Control tools for simulator sessions created and owned by this server.

The server does not attach to sessions created by other applications.

Installation

Python >=3.11,<3.13 is supported. Install Core, this package, and the adapter required by the selected backend in the same environment.

conda create -n unirobosim-mcp python=3.12 pip -y
conda activate unirobosim-mcp

git clone https://github.com/GitHofee/UniRoboSim.git
git clone https://github.com/GitHofee/UniRoboSim-mcp.git
git clone https://github.com/GitHofee/UniRoboSim-mujoco.git  # example backend

python -m pip install ./UniRoboSim ./UniRoboSim-mcp ./UniRoboSim-mujoco

General deployments use the current MCP 2.x runtime. Isaac Lab 3.0 environments retain their verified Pydantic and Uvicorn pins, so install the compatibility extra there:

python -m pip install './UniRoboSim-mcp[isaaclab]'

The extra selects MCP 1.10.1; it exposes the same UniRoboSim tool catalog and was verified through the real stdio protocol with Isaac Sim 6.0.1.

Related MCP server: gazebo-mcp

Evidence profile

unirobosim-mcp --root /absolute/path/to/approved/evidence

UNIROBOSIM_EVIDENCE_ROOT may be used instead of --root:

export UNIROBOSIM_EVIDENCE_ROOT=/absolute/path/to/approved/evidence
unirobosim-mcp

Absolute paths, traversal, escaping symlinks, unapproved extensions, oversized files, excessive scans, and excessive result counts are rejected.

Control profile

Control must be enabled explicitly. Local asset files are denied unless their parent tree is allowlisted with --asset-root.

unirobosim-mcp \
  --root /absolute/path/to/approved/evidence \
  --enable-control \
  --asset-root /absolute/path/to/approved/assets \
  --max-sessions 2 \
  --lease-timeout-seconds 300

Read API

Read tools require a session ID but not the write lease.

simulation_get_entity reports the canonical path, entity kind, original MCP configuration, simulation tick, array shapes and dtypes, and type-specific data. include_values=true includes bounded values; include_contact=true adds rigid-body contact state.

simulation_capture_camera is not a desktop or browser screenshot. It calls the selected backend through Camera.read("rgb"), validates the canonical [environment,height,width,3] uint8 buffer, and encodes that buffer as PNG. save_to_evidence=true also writes the image under <root>/screenshots/ and returns its SHA-256 digest and dimensions.

Control API

All mutations require the opaque lease_id returned by simulation_create and a unique command_id.

Repeated use of a command_id with identical input returns the cached result with idempotent_replay=true. Reusing that identifier with different input is rejected. Expired sessions are closed automatically. Every applied or rejected mutation is written to mcp-control-audit.jsonl; lease values are excluded from the audit record.

Agent operating rule

An agent using the Control profile must follow this sequence:

1. Call simulation_list_backends and select an available backend explicitly.

2. Call simulation_create; retain the returned lease only for write operations.

3. Add all entities with unique command identifiers, then call simulation_start.

4. Use simulation_scene_snapshot to discover canonical entity and camera paths.

5. Use simulation_get_entity for targeted state and simulation_capture_camera for visual verification.

6. Reuse a command identifier only to retry the identical write request.

7. Call simulation_close for every created session, including failed workflows.

The agent must not infer backend support from tool availability. Unsupported simulator capabilities are reported by capability negotiation or by the selected adapter.

Loopback HTTP

unirobosim-mcp \
  --root /absolute/path/to/approved/evidence \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8766

Unauthenticated HTTP is restricted to 127.0.0.1, localhost, or ::1. Remote deployment requires an authenticated and authorized gateway. Control mode must not be exposed directly on an untrusted network.

Programmatic embedding

from pathlib import Path

from unirobosim_mcp import ControlLimits, EvidenceLimits, SimulationControl, create_server

root = Path("/approved/evidence")
control = SimulationControl(
    root,
    asset_roots=(Path("/approved/assets"),),
    limits=ControlLimits(max_sessions=1, lease_timeout_seconds=120),
)
server = create_server(
    root,
    limits=EvidenceLimits(max_results=50, max_query_items=100),
    control=control,
)
server.run(transport="stdio")

Verification

python -m pip install -e '.[dev]'
ruff format --check src tests
ruff check src tests
mypy src
coverage run -m pytest
coverage report

Release acceptance calls every published MCP tool through a real in-process MCP client. Additional contract tests cover all supported entity types and command families, leases, idempotency, expiration, allowlisted assets, resource limits, audit records, PNG encoding, and saved screenshot evidence. Native acceptance is executed separately for each installed simulator adapter; a feature is not reported as passed for a backend unless that native run succeeds.

Core contracts and adapter installation are documented in UniRoboSim Core.