lamcp 0.1.0

Lambda MCP: teach your LLM to do Grasshopper tricks.

LAMCP

LAmbda MCP: teach your LLM to do Grasshopper tricks.

Lets Claude Code (or any MCP client) introspect and mutate a live Grasshopper session in real time: inspect the canvas, wire components, read/write slider values, run RhinoCommon calls, hot-reload modules -all from inside an AI agent loop, without rebuilding userobjects or restarting Rhino.

Architecture

LLM ──MCP stdio──▶ lamcp (Python 3.10+)
                          │
                          │  HTTP POST /exec  {"code": "...", "timeout": 30}
                          ▼
                  LAMCP Bridge GH component (Rhino 8 CPython 3.9)
                     ├─ http.server on 127.0.0.1:8765
                     ├─ exec() with shared globals
                     └─ returns {stdout, stderr, result, error}

Why split: Rhino 8's CPython runtime is pinned to 3.9. fastmcp and the underlying mcp SDK require 3.10+. So the MCP-speaking half runs in a system Python and forwards over loopback HTTP to a stdlib-only HTTP server living inside Rhino as a regular Grasshopper component.

Setup

1. Install the MCP server

git clone https://github.com/gramaziokohler/lamcp.git
cd lamcp
uv pip install -e .
# or: pip install -e .

2. Register with Claude Code (or whatever LLM you use)

Add to ~/.claude.json:

{
  "mcpServers": {
    "lamcp": {
      "command": "lamcp"
    }
  }
}

If lamcp isn't on PATH, use the absolute path to the venv's script:

{
  "mcpServers": {
    "lamcp": {
      "command": "/absolute/path/to/.venv/bin/lamcp"
    }
  }
}

Restart Claude Code so it discovers the new MCP server.

3. Install the bridge in Grasshopper

Option A — drop the pre-built userobject (recommended).

1. Download Lamcp_Bridge.ghuser from the latest release.
2. In Grasshopper: File → Special Folders → Components Folder. Move the .ghuser file there.
3. Restart Grasshopper. LAMCP Bridge appears under the LAMCP tab.
4. Drop it on the canvas, wire a Boolean Toggle (set to True) into enable. The status output reads listening on http://127.0.0.1:8765.

Option B — paste the source manually (for hacking).

1. Drop a Python 3 Script component on the canvas. Paste the contents of grasshopper/Lamcp_Bridge/code.py in.
2. Add two inputs: enable (bool) and port (int). Add one output: status.
3. Wire a Boolean Toggle (set to True) into enable.
4. The status output should read listening on http://127.0.0.1:8765.

Either way, your MCP client now has a run_python_script tool that exec()s code inside your live Rhino session.

Tools exposed

Tool	Purpose
run_python_script	exec() arbitrary Python inside Rhino, capture stdout / stderr / repr(_)
unload_python_modules	drop sys.modules[prefix.*] so the next import re-reads from disk
bridge_health	ping the bridge to verify it's reachable

Return contract for run_python_script

{
  "stdout": "...",            // captured stdout
  "stderr": "...",            // captured stderr
  "result": "repr of _",      // assign to `_` to return a value
  "error": null               // formatted traceback if exception raised
}

Globals persist between calls, so you can import once and reuse:

# call 1
import scriptcontext as sc; doc = sc.doc.ActiveDoc
# call 2
print(doc.Name)   # `doc` is still bound

Environment variables

Variable	Default	Purpose
LAMCP_BRIDGE_URL	http://127.0.0.1:8765	URL of the bridge's HTTP server

Caveats

• UI thread: code runs on the HTTP server thread, not the Rhino UI thread. Most read-only RhinoCommon / Grasshopper access works cross-thread, but heavy mutations (bulk RemoveObject, etc.) can crash Rhino. Eto-based UI marshalling is a planned addition.
• isinstance doesn't always work: in Rhino 8 CPython, isinstance against concrete .NET types often returns False due to interface interop. Use obj.GetType().Name == "..." instead.
• RemoveSource(IGH_Param) is a silent no-op: use the RemoveSource(Guid) overload.
• float(System.Decimal) raises: wrap with System.Convert.ToDouble(x) or float(str(x)).

Security

The bridge listens on 127.0.0.1 only and accepts no auth: it runs arbitrary Python in your Rhino with no sandboxing. Never expose it beyond localhost, and stop it (enable=False) when you're done.

Development

Install with the dev extra to pull in ruff:

pip install -e ".[dev]"

Lint + format checks (same commands CI runs):

ruff check .                # lint
ruff format --check .       # formatting (non-destructive)

Auto-fix:

ruff check . --fix          # fix lint issues
ruff format .               # reformat

For one-off runs without installing into your env, uvx ruff ... works identically.

Releases are tag-driven — see RELEASING.md.

License

MIT