Rhino MCP

The low-friction Rhino and Grasshopper bridge for Codex, Claude, and Cursor.

The Windows experience is deliberately short:

1. Download and run RhinoMCP-Windows-Setup.

2. Choose Codex, Claude, or Cursor.

3. In Codex, begin a request with /RhinoMCP. Rhino, its bridge, and the Chrome connection page open automatically when needed.

No Rhino Package Manager, repository clone, Python installation, uv, Conda environment, Rhino Python script, Grasshopper file, Python-path change, terminal command, or hand-edited MCP configuration is part of normal setup.

Install

Requires Rhino 8.0 or newer and the AI client you want to use. Rhino 8.1 is supported without updating Rhino. Close Rhino, download the single RhinoMCP-Windows-Setup-*.exe file from the latest release, and double-click it. The installer asks for the AI client and then automatically:

• installs the Rhino and Grasshopper bridges using Rhino's bundled installer;

• removes every older Rhino-MCP-Easy package version before installing the new one;

• registers the active .rhp with Rhino and clears only Rhino MCP's stale plug-in discovery cache;

• installs a self-contained MCP server with its complete runtime;

• writes the Codex, Claude, or Cursor MCP entry safely;

• installs the Codex $rhino-mcp workflow and /RhinoMCP routing guidance;

• selects the safe Grasshopper tool profile;

• runs the doctor checks; and

• adds a normal entry to Windows Installed apps for clean removal.

The installer does not need Rhino to be online, does not download dependencies, and Rhino MCP never updates itself. Installing a different version always requires deliberately running another installer. Running that installer performs a clean in-place replacement: it removes only Rhino MCP's old package versions and bundled server files, installs the selected version, and verifies that Rhino's active manifest.txt and both plug-in runtimes match it. It also unblocks the installed files and verifies Rhino's per-user Name, FileName, and startup registration. Rhino models, unrelated plug-ins, and other application files are not touched.

When Rhino starts, it automatically opens a local connection dashboard in Google Chrome when Chrome is available, falling back to the Windows default browser. It works without internet access and does not require a separate service or browser extension. If Codex was selected during setup, Rhino also opens the installed Codex/ChatGPT desktop app after startup. If it is already running, Rhino brings its window forward instead of opening a duplicate. The dashboard says Codex is open — start writing and includes an Open Codex button in case the app is closed later. The dashboard keeps the required /RhinoMCP prompt prefix visible with a one-click copy button. On current OpenAI desktop installations, Codex may appear inside the app named ChatGPT; choose Codex from the top-left menu if it is not already the default view.

Related MCP server: Grasshopper MCP

Architecture regulation checks

Rhino MCP includes a compact, offline search index built from the supplied Google Drive regulation library. The original files are preserved outside this public source repository; the bundled index stores searchable page text, source metadata, and links back to the originals. It is a fixed snapshot and never syncs or updates itself. The snapshot contains 289 source files, with 272 searchable documents and 7,896 indexed pages. Azerbaijani, Russian, and English OCR recovered 553 scanned PDF pages and 66 image/TIFF sheets without extraction errors.

For architecture, building, accessibility, fire-safety, structural, sanitary, energy, drainage, shelter, site-planning, or related Grasshopper requests, every MCP client receives an always-on workflow instruction to:

1. establish the jurisdiction, occupancy/project type, design stage, and constraints;

2. search the regulatory library before proposing regulated dimensions or editing the model;

3. cite the exact document title, Drive source ID, and page for each requirement;

4. separate verified source requirements from recommendations and inference; and

5. flag missing evidence, conflicts, uncertain applicability, and the need for a licensed local review.

Document text is treated as untrusted reference data, not as executable instructions. The AI must not invent code values or describe its review as a permit, approval, or legal compliance certificate.

The always-available regulation tools are:

• regulation_library_status

• search_regulations

• get_regulation_page

• architecture_regulation_checklist

The search expands common English architecture terms into Azerbaijani and Russian so the model can find the multilingual source material. Check the installed snapshot or try a search with:

rhino-mcp regulations status
rhino-mcp regulations search "fire evacuation stairs"

The source collection and its effective legal status have not been independently certified. A responsible architect or engineer must confirm jurisdiction, applicability, amendments, conflicts, and current requirements before construction.

For managed or silent deployment, the same download supports:

.\RhinoMCP-Windows-Setup-0.4.7.exe /CLIENT=codex /SILENT

Valid client values are codex, claude, and cursor. For Codex, type a request such as /RhinoMCP create a test cube. The installed workflow first runs ensure_rhino_ready: if Rhino is closed it launches Rhino 8, waits for the bridge, and displays the live connection page in Chrome before continuing. Claude and Cursor users should open or restart their selected client after setup. Codex users can run /mcp to confirm that rhino-mcp is enabled.

/RhinoMCP is an enforced routing prefix in the prompt, not an undocumented Codex menu command. Codex's supported selectable shortcut is $rhino-mcp. The installer also adds /prompts:RhinoMCP for Codex CLI and IDE versions that still support custom prompts.

Connection dashboard

Every time Rhino launches, Rhino MCP opens one dashboard tab in Chrome. If Chrome is not installed, it uses the Windows default browser instead. The page shows the required /RhinoMCP prefix and the live state of:

• Rhino Bridge — connected or stopped

• Codex / Claude / Cursor — connected, waiting, or not configured

• Grasshopper — connected or unavailable

• Regulations — loaded or not installed

Below the live services, Project files shows the exact path of the active Rhino model and Grasshopper definition. Installed files shows the Rhino plug-in, Grasshopper add-on, bundled MCP server, settings, regulatory database, AI-client configuration, Codex routing files, and installer log with Found, Missing, or Unsaved states and a copy-path button.

If Grasshopper does not finish loading, the dashboard shows a Needs attention diagnostic. It checks common plug-in locations for likely blockers and displays their paths without changing or deleting third-party files. A breakpoint saying that a component library was built against a newer Grasshopper SDK means that add-on must be replaced with a build compatible with the installed Rhino version, or disabled before restarting Rhino.

The page refreshes its status once per second. If Rhino closes, the existing tab changes to Rhino is offline and keeps trying; when Rhino reopens, it reconnects automatically. The tab can be closed at any time. Run RhinoMCPDashboard in Rhino to open it again.

The default address is http://127.0.0.1:9877/. It is served directly by the Rhino plug-in, binds only to this computer, loads no web assets, and sends nothing to the internet. Status and file information is read-only. Its only action is the explicit Open Codex button, protected by a private per-launch token; it opens the desktop app and never edits a model or file. If that port is already occupied, Rhino MCP chooses a private local fallback automatically and opens the correct address.

What appears in Rhino

The Rhino MCP connection strip appears automatically in the top-right of the active modeling viewport every time Rhino launches. It stays visible without taking up side-panel space, follows the active viewport, and appears again on the next Rhino launch even if it was hidden during the previous session.

The headline says CONNECTED — READY, CODEX OPEN — START WRITING, RHINO READY — GH OFFLINE, WAITING FOR CODEX/CLAUDE/CURSOR, SETUP NEEDED, or BRIDGE STOPPED. Four live dots show:

• Bridge — green when Rhino is listening

• Codex / Claude / Cursor — green when the selected AI client is connected

• Grasshopper — green when Grasshopper is open and its bridge is available

• Rules — green when the offline regulatory library is loaded

The strip is deliberately not included in viewport images returned to the AI. Run RhinoMCP to hide or show it. For troubleshooting, Rhino also provides:

• RhinoMCPDashboard — reopen the browser dashboard

• RhinoMCPStatus — show the strip and print the full status, ports, and dashboard URL

• RhinoMCPRestart — restart the local Rhino bridge

• RhinoMCPTest — create, verify, and automatically remove a test cube

The installer includes both Rhino 8 runtime builds. Rhino automatically uses net7.0 in its normal runtime or net48 if Rhino is configured for the legacy .NET Framework runtime; the user does not need to choose or configure this. The installer writes Rhino's documented per-user plug-in registration and removes only obsolete Rhino MCP cache entries before the next launch. If an individual bridge or dashboard service cannot start, the plug-in stays loaded so RhinoMCPRestart, RhinoMCPStatus, and the other recovery commands remain available.

The connection test creates a one-unit cube, verifies it, and removes it. If cleanup is disabled, the test cube is left in the document.

Advanced commands

Source and Python-package installations can use:

rhino-mcp setup [codex|claude|cursor]
rhino-mcp doctor [--json]
rhino-mcp status [--json]
rhino-mcp update
rhino-mcp uninstall [--all]
rhino-mcp config [codex|claude|cursor]
rhino-mcp config --profile basic|grasshopper|developer
rhino-mcp config --auto-launch-client
rhino-mcp config --no-auto-launch-client

doctor reports pass/fail/wait states for the package, settings, every AI client, Rhino, Grasshopper, and the server launcher. Rhino and Grasshopper being closed are shown as WAIT, with the exact next action, rather than as socket traces.

Tool profiles

Basic (default)

The safe everyday set:

• rhino_status

• ensure_rhino_ready

• get_scene_summary

• list_layers

• list_objects

• get_scene_changes

• create_geometry

• modify_objects

• delete_objects

• organize_layers

• batch_geometry

• test_connection

• capture_viewport

Grasshopper

Adds paginated definition context, selected/object inspection, and recompute tools. The bundled .gha starts its bridge automatically when Grasshopper opens; there is no .gh definition or Python component to load.

Developer

Explicitly adds arbitrary Rhino and Grasshopper Python tools. They are absent from the Basic and Grasshopper tool schemas, so an AI client cannot discover or call them accidentally. Safe high-level operations are still preferred.

Safe editing behavior

• Every modifying request gets a named Rhino undo record.

• A batch performs all operations in one transaction and redraws once.

• Geometry and layer tools accept dry_run: true for validation and preview.

• Deletes require explicit Rhino object IDs.

• Read results are structured objects, not JSON encoded inside strings.

• Object and Grasshopper lists are filtered and paginated.

• get_scene_changes sends only additions, edits, and deletions since a supplied scene version.

Example prompt:

/RhinoMCP Create a 10 × 8 × 3 box on a layer named Massing. Dry-run it first, then create it
and show me a compressed viewport capture.

Reliability and performance

• 4-byte length-prefixed messages replace the old giant receive buffer.

• Requests are read in bounded 64 KiB chunks with a 64 MiB hard limit.

• Rhino TCP and Grasshopper HTTP connections are kept alive and reused.

• A failed safe read reconnects once automatically.

• Mutations are never retried blindly, preventing duplicate geometry.

• Short-lived scene metadata is cached and invalidated after edits.

• Scene changes and large documents are paginated instead of repeatedly returned in full.

• Grasshopper context is simplified by default.

• View captures default to compressed JPEG with configurable size and quality.

• Socket work and image encoding run away from Rhino's UI thread; only Rhino API calls are marshalled onto it.

• Tool descriptions and normal responses are intentionally compact to reduce model token usage.

Change image defaults with:

rhino-mcp config --image-size 1280 --image-quality 82

Developer build

Python package:

python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest -q
python -m build

Rhino 8 plug-in and Package Manager archive:

./scripts/build-yak.sh Release

The script builds RhinoMCP.rhp, RhinoMCP.Grasshopper.gha, and a .yak under dist/.

Complete Windows installer (run in PowerShell on Windows):

python -m pip install -e ".[dev]" "pyinstaller==6.22.2"
choco install innosetup --yes
.\scripts\build-windows-installer.ps1

CI compiles and smoke-tests the bundled Windows executable and the single-file installer. Tagged releases attach the installer, its SHA-256 checksum, and the manual developer artifacts.

Architecture

Codex `/RhinoMCP ...` / Claude / Cursor
        │ MCP stdio
        ▼
bundled rhino-mcp.exe
        ├── cold-start Rhino + display Chrome dashboard
        ├── offline regulation search index
        │
        │ framed, persistent localhost TCP
        ▼
RhinoMCP.rhp ── Rhino document + visible viewport status strip
        ├── local status dashboard + protected Open Codex action
        │
        └── RhinoMCP.Grasshopper.gha (persistent localhost HTTP)

Both bridges and the dashboard bind only to 127.0.0.1; they are not exposed to the network.

License

MIT. This repository is standalone and has no upstream Git remote.