GOLEM-3DMCP

"Shaped from clay, brought to life by words"

The most powerful MCP server for Rhinoceros 3D — 89 tools giving AI full read/write access to Rhino 8.

GOLEM-3DMCP implements the Model Context Protocol to give AI agents direct, programmatic control of Rhino 8 — create geometry, run booleans, drive Grasshopper, capture viewports, and execute arbitrary Python scripts, all through natural language.

Works with Claude Code, Cursor, Windsurf, and any MCP-compatible host.

An entire city generated in Rhino 8 through GOLEM-3DMCP — roads, skyscrapers, houses, trees, people, vehicles, a stadium, bridge, ferris wheel, harbor, wind turbines, and a floating GOLEM hologram. All created by Claude Code using natural language commands.

Watch the full demo on YouTube

Full city overview — ground, roads, buildings, park, harbor, sky

Skyline view — skyscrapers, bridge, wind turbines, floating GOLEM hologram

Close-up — GOLEM monument plaza, residential buildings, fountain

Street level — vehicles, people, street lamps, stadium, harbor with boats

pip install golem-3dmcp

That's it. Three commands to go from zero to AI-powered Rhino:

# 1. Install
pip install golem-3dmcp

# 2. Deploy the Rhino plugin (one-time)
golem install-rhino

# 3. Verify everything works
golem doctor

Add to your MCP configuration (Claude Code, Cursor, Windsurf, etc.):

{
  "mcpServers": {
    "golem-3dmcp": {
      "command": "uvx",
      "args": ["golem-3dmcp"]
    }
  }
}

Start talking to Rhino through AI.

How the 89 is counted — two ways that agree:

# 1. Registrations in the shipped package
grep -c '@mcp.tool' src/golem_3dmcp/tools/*.py | awk -F: '{s+=$2} END {print s}'   # 89

# 2. What the running server advertises over MCP
python -c "import asyncio, importlib, golem_3dmcp.server as s; \
[importlib.import_module('golem_3dmcp.tools.' + m) for m in \
 ('scene','creation','operations','surfaces','manipulation','viewport','files','grasshopper','scripting')]; \
print(len(asyncio.run(s.mcp.list_tools())))"                                       # 89

docs/TOOL_REFERENCE.md enumerates 105 entries: that is the Rhino plugin's RPC method surface, which is larger than the MCP tool surface. 89 is the number of tools an MCP client sees.

See Tool Reference for the complete API with parameters and examples.

 AI Agent (Claude Code / Cursor / Windsurf)
      |
      |  MCP (stdio, JSON-RPC)
      v
+---------------------------+
|     GOLEM MCP Server      |
|     Python 3.10+          |
|     FastMCP + 9 tool      |
|     modules               |
+---------------------------+
      |
      |  TCP 127.0.0.1:9876
      |  Length-prefixed JSON
      v
+---------------------------+
|     Rhino Plugin          |
|     Python 3.9 (embedded) |
|     TCP Server            |
|     9 handler modules     |
+---------------------------+
      |
      |  RhinoCommon + rhinoscriptsyntax
      v
+---------------------------+       +-------------------------+
|     Rhinoceros 3D         | <---> |   Grasshopper           |
|     Document, Geometry,   |       |   Sub-server :9877      |
|     Layers, Views         |       |   Definitions, Params   |
+---------------------------+       +-------------------------+

Create and combine geometry:

Create a 100 x 50 x 30 box on a layer called 'Structure',
then boolean-union it with a sphere of radius 20 centred at [50, 25, 30].

Query the scene:

List all objects on the 'Walls' layer and tell me their volumes.

Drive Grasshopper:

Open parametric_facade.gh, set the 'PanelCount' slider to 24,
recompute, and bake the result to a 'Facade' layer.

Capture a viewport:

Set perspective view to shaded mode, zoom to extents, and capture a screenshot.

Execute arbitrary Python:

import Rhino.Geometry as rg
pts = [rg.Point3d(i*10, 0, i**2) for i in range(20)]
crv = rg.Curve.CreateInterpolatedCurve(pts, 3)
sc.doc.Objects.AddCurve(crv)
__result__ = {"point_count": len(pts), "length": crv.GetLength()}

1. Open Rhino 8
2. Open Script Editor: Tools > Python Script > Edit
3. Open startup.py (deployed by golem install-rhino) and click Run

GOLEM-3DMCP: Starting server on 127.0.0.1:9876...
GOLEM-3DMCP: Server started successfully!
GOLEM-3DMCP: 135 handler methods registered.

Auto-start on every Rhino launch: Tools > Options > RhinoScript > Startup Scripts > Add startup.py

The Rhino plugin runs inside Rhino's embedded Python 3.9 with zero external dependencies.

Run golem doctor to diagnose issues automatically.

See Troubleshooting Guide for detailed solutions.

• Architecture — System design, threading model, data flow
• Tool Reference — Plugin RPC methods with parameters and examples (105 entries; the MCP server exposes 89 of them as tools)
• Protocol Specification — TCP wire format, message framing, error codes
• Troubleshooting — Common issues and solutions

# Unit tests (no Rhino needed)
pytest tests/ -v --ignore=tests/test_integration.py

# Full suite (integration tests auto-skip if Rhino not running)
pytest tests/ -v

# Integration tests only (requires Rhino + plugin running)
pytest tests/test_integration.py -v -m integration

This repository uses two branches:

• Develop on main — all tool modules, Rhino plugin, tests, and documentation live here.
• Release from the PyPI branch — packaging structure (pyproject.toml, src/ layout, publish scripts) is managed separately so releases don't pollute the development history.

main                          ← development
  └── main  ← PyPI releases (pip install golem-3dmcp)

golem-3dmcp/
├── src/golem_3dmcp/           # MCP Server (pip install golem-3dmcp)
│   ├── cli.py                 #   CLI entry point (golem command)
│   ├── server.py              #   FastMCP server
│   ├── connection.py          #   TCP client (singleton, thread-safe)
│   ├── protocol.py            #   Wire format: 4-byte length prefix + JSON
│   ├── config.py              #   Environment variable configuration
│   ├── models/                #   Pydantic data models
│   ├── tools/                 #   9 MCP tool modules
│   └── _rhino_plugin/         #   Bundled Rhino plugin (deployed via CLI)
├── tests/                     # 245 tests (pytest --collect-only)
├── docs/                      # Architecture, protocol spec, tool reference
└── pyproject.toml             # Package definition

We welcome contributions! Here's how to get started:

# Clone the repository
git clone https://github.com/TheKingHippopotamus/GOLEM-3DMCP-Rhino-.git
cd GOLEM-3DMCP-Rhino-

# Create virtual environment (Python 3.10+ required)
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

All CI checks must pass before merging:

# Lint
ruff check src/ tests/

# Type check (strict mode)
mypy src/golem_3dmcp/ --ignore-missing-imports

# Unit tests (no Rhino needed)
pytest tests/ -v --ignore=tests/test_integration.py

# Integration tests (requires Rhino 8 + plugin running)
pytest tests/test_integration.py -v -m integration

• Two Python runtimes — The MCP server runs on Python 3.10+, but _rhino_plugin/ runs inside Rhino's embedded Python 3.9. They communicate over TCP. Don't add 3.10+ syntax to the plugin.
• _rhino_plugin/ is excluded from mypy — It uses Rhino-specific imports (Rhino.*, Grasshopper.*, clr) that don't exist in a standard environment.
• Tool registration — Tools use @mcp.tool() decorators. Each tool module imports mcp from server.py. Add new tools in src/golem_3dmcp/tools/ and register the module in server.py:main().
• Thread safety — RhinoConnection is a thread-safe singleton with a lock around socket I/O. Don't bypass send_command().
• Protocol — TCP messages use 4-byte length-prefixed JSON. See protocol.py for the wire format.

1. Create a feature branch from main
2. Make your changes
3. Ensure all checks pass (ruff, mypy, pytest)
4. Submit a PR with a clear description

See CONTRIBUTING.md for the full guide.

MIT License. See LICENSE for details.

Created by King Hippopotamus
Built by NEXUS AI — 195 autonomous agents | 20 departments | 11 tiers

Built with: FastMCP · RhinoCommon · rhinoscriptsyntax · Grasshopper SDK

"From formless clay, through the power of words, form emerges."