Blender Optics — dedicated MCP server

A standalone MCP server that lets an MCP client (e.g. Claude Desktop / Claude Code) drive a running Blender Optics Simulator scene: build canonical setups, read the full optical state (ports, world normals, beam path, detector readings), align, swap parts, position elements relative to one another, scan, and render.

It talks to the add-on through a tiny localhost socket bridge built into the add-on (optical_alignment_sim/bridge.py), so it works against the live Blender you already have open — no headless re-launch, no file round-trips.

MCP client  ──stdio──▶  optics_mcp_server.py  ──TCP 127.0.0.1:9765──▶  Blender add-on bridge ──▶ optics_api

1. Start the bridge in Blender

In the running Blender: View3D ▸ Sidebar (N) ▸ Optics ▸ Simulation ▸ Start MCP Bridge. The status line shows MCP bridge: 127.0.0.1:9765 (live). (Or tick Auto-start bridge in the add-on preferences to start it on load. Change the port there if 9765 is taken.)

Only the add-on's whitelisted optics_api functions are reachable, and the socket binds to 127.0.0.1 only.

2. Run the MCP server

The server is a packaged console app — blender-optics-mcp. Pick whichever you like:

# zero-install, one line (recommended) — runs the packaged entry point
uvx blender-optics-mcp                      # once published to PyPI
uvx --from ./mcp blender-optics-mcp         # straight from this repo, no publish needed

# or install it
pipx install blender-optics-mcp             # (PyPI)  /  pipx install ./mcp   (from source)
pip install ./mcp && blender-optics-mcp     # into the current environment

# or just run the single file (needs `pip install "mcp[cli]"`)
OPTICS_BRIDGE_PORT=9765 python3 optics_mcp_server.py

Environment:

• OPTICS_BRIDGE_PORT — bridge port (default 9765, must match the add-on preference).
• OPTICS_BRIDGE_HOST — default 127.0.0.1.

3. Wire it into an MCP client

With the packaged entry point the client config is a single command — no absolute script path:

{
  "mcpServers": {
    "blender-optics": {
      "command": "uvx",
      "args": ["blender-optics-mcp"],
      "env": { "OPTICS_BRIDGE_PORT": "9765" }
    }
  }
}

("command": "blender-optics-mcp" works too once it's installed on your PATH; or, from a checkout, "command": "uvx", "args": ["--from", "/absolute/path/to/mcp", "blender-optics-mcp"].)

Distribution (MCP Registry / PyPI)

This folder is a self-contained Python distribution:

• pyproject.toml — builds blender-optics-mcp (a single-module wheel; depends only on mcp[cli]). python -m build → publish to PyPI with twine.
• server.json — the MCP Registry manifest (namespace io.github.emircbngl/..., PyPI package, stdio transport). Publish/validate it with the official mcp-publisher CLI (it authenticates via GitHub and checks the schema — confirm the $schema version it expects at submission time, as the registry schema evolves).

Tools

The server mirrors the add-on's full optics_api surface — the bridge auto-derives its allow-list from optics_api's public functions, so every tool below maps 1:1 to a core API call.

Notes

• The bridge dispatches every call onto Blender's main thread (bpy is not thread-safe), so tools are serialized and safe.
• An interactively-authenticated Blender session is required for live edits; the server itself is stateless and reconnects per call.