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)

1. Download the latest synthgen_mcp.zip from releases (or build it yourself — see below)

2. Install in Blender: Edit → Preferences → Add-ons → Install from Disk → select the zip

3. Enable "Synthgen MCP" — first enable installs dependencies (~15s one-time)

4. 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:

1. Set Blender's BLENDER_USER_SCRIPTS environment variable to point to the addon/ directory
2. 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