blender-synthgen-mcp

Procedural 3D synthetic-data toolkit for Blender — grounded node schemas, a lazy scene-graph walker, and a Houdini→Blender knowledge base, delivered as a self-contained Blender addon with an MCP server built in.

Quick Install (Blender addon)

Download the latest synthgen_mcp.zip from releases (or build it yourself — see below)
Install in Blender: Edit → Preferences → Add-ons → Install from Disk → select the zip
Enable "Synthgen MCP" — first enable installs dependencies (~15s one-time)
Connect from your IDE:
Claude Code / Cursor / VS Code — add to your MCP config:
```
{"synthgen": {"url": "http://localhost:8400/sse"}}
```

That's it. The addon runs an SSE MCP server inside Blender on port 8400. Your IDE connects to it and gets 33 grounded tools for procedural 3D work.

N-panel controls

In the 3D viewport sidebar (N) → "Synthgen MCP" tab:

Start/Stop — toggle the MCP server
Copy MCP Config — copies the connection JSON to your clipboard
Server status — shows running state and port

Change the port

Edit → Preferences → Add-ons → Synthgen MCP → Port (default 8400)

What's inside

The addon bundles:

33 MCP tools across 5 layers (setup, procedural authoring, graph introspection, pipeline, verification)
Grounding data — extracted node schemas for Blender 5.2 (Geometry Nodes, Shader, Compositor)
Main-thread executor — marshals all bpy calls safely from the MCP background thread

Tool layers

Layer	Tools	Purpose
Setup	`create_object`, `create_material`, `assign_material`, `set_parent`, `configure_render`, `import_asset`, `edit_mesh`, `add_keyframes`	Scene building blocks
Procedural	`add_gn_modifier`, `add_node`, `link_sockets`, `set_node_property`, `set_socket_default`, `expose_parameter`, `add_driver`, `wire_attr_bridge`, `wire_compositor_pass`	Node graph authoring with grounded identifiers
Introspection	`graph_nodes`, `graph_neighbors`, `graph_reachable`, `graph_impact_set`, `graph_attribute_trace`, `graph_snapshot`	Live scene-graph traversal
Pipeline	`set_parameter`, `render`, `sweep`, `export_labels`	Parameter sweeps + provenance
Schema	`schema_find`, `schema_show`, `schema_socket`, `schema_setting`	Query node schemas
Verify	`verify_attribute_exists`	Runtime attribute checks
Escape hatch	`execute_python`	Direct bpy access (ungrounded)

Why this exists

Transport (a Blender MCP) is a commodity. The moat is version-exact grounding + a build→verify loop. LLMs hallucinate node/socket identifiers, so we extract the real schema from Blender itself and give the agent tools to query it — never trusting model memory. The same idea, one level up, becomes the scene-graph walker: a lazy, pull-based view over the live scene so the agent can traverse real relationships.

Governing principle (see knowledge/procedural_paradigm.md): derive, don't set. Native Blender is imperative/destructive; the agent must live on the procedural island (Geometry Nodes / shader / compositor / drivers), because you cannot sweep a hand-edit, and sweeping a parameter space is the whole job.

Build from source

# Install dev dependencies
pip install -e ".[dev]"

# Run tests (offline — no Blender needed)
pytest

# Build the addon zip
python scripts/build_addon.py
# → dist/synthgen_mcp.zip

Development mode

For development without rebuilding the zip each time:

Set Blender's BLENDER_USER_SCRIPTS environment variable to point to the addon/ directory
Or symlink addon/synthgen_mcp/ into Blender's addons folder

The addon auto-detects whether it's running from source (adds src/ to path) or from a built zip (uses bundled files).

Grounded against

Blender 5.2.0 LTS — Geometry Nodes (360), Shader (118), Compositor (168) node schemas
Houdini 22.0.368 — SOP/VOP/COP node schemas (for the crosswalks)

Regenerate for another version with the extractors in src/synthgen/extract/ (run inside Blender / hython); drop results in data/schemas/<app-version>/.

Schema CLI (standalone)

The schema query tool works without Blender:

python -m synthgen.schema.query stats
python -m synthgen.schema.query show "Store Named Attribute"
python -m synthgen.schema.query --shader show "Attribute"
python -m synthgen.schema.query --compositor find "Cryptomatte"

Architecture

IDE (Claude Code / Cursor / VS Code)
  │
  │  MCP protocol over SSE HTTP
  │
  ▼
Blender addon (synthgen_mcp)
  ├── SSE MCP server (background thread, port 8400)
  ├── Main-thread executor (bpy.app.timers queue)
  ├── 33 grounded tools
  ├── Bundled schema data
  └── N-panel UI

See ROADMAP.md for project status and phase details.

License

MIT

blender-mcp-synthgen