Codex Blender

Codex Blender

Codex Blender is an open-source local bridge for controlling Blender from Codex or a terminal command. It runs a small HTTP server inside Blender, then accepts structured JSON commands for scene creation, asset import, rendering, saving, and inspection.

This is not a cloud connector. Blender runs locally on your machine.

What It Can And Cannot Do

Codex Blender can create procedural scenes, import local assets, apply materials and textures, place reference images, render, save, export, inspect objects, and perform simple transforms or animations through structured commands.

It cannot turn any arbitrary image into a perfect production 3D model by itself. Image-to-model work is an iterative workflow: add a reference, create or import a base model, adjust geometry/materials/camera, render, compare, and repeat.

For a repeatable reference-vs-render process, see docs/render-comparison.md.

Create a side-by-side comparison contact sheet:

python scripts\create_contact_sheet.py assets\references\modern_table_reference.png assets\logo.png renders\compare\table_side_by_side_v001.png --metadata-output renders\compare\reports\table_v001.json

Compute rough image-difference metrics:

python scripts\compare_images.py assets\references\modern_table_reference.png assets\logo.png --output renders\compare\reports\table_metrics_v001.json

Create a comparison iteration report:

python scripts\create_iteration_report.py assets\references\modern_table_reference.png renders\compare\reports\table_iteration_v001.json --markdown-output renders\compare\reports\table_iteration_v001.md --note "Initial comparison pass."

For release publishing steps and the confirmation checklist, see docs/github-release.md.

Verify the release ZIP locally:

python scripts\verify_release_asset.py --build

Generate release draft metadata without publishing:

python scripts\generate_release_draft.py --build

Features

• Start and stop a local Blender bridge at http://127.0.0.1:8765.
• Create a starter room scene.
• Create an outdoor road scene with sidewalks, curbs, markings, varied trees, benches, signs, bushes, rocks, and street lights.
• Create a reusable modern wooden table model.
• Create a reusable modern chair model.
• Create a reusable modern sofa model.
• Create a reusable indoor plant model.
• Create reusable floor, table, and ceiling lamp models with real Blender lights.
• Create reusable procedural primitives such as beveled boxes, panels, glass panels, cylinders, cones, planes, spheres, and labels.
• Create procedural furniture presets such as shelves, cabinets, desks, beds, doors, windows, and wall art.
• Create procedural architecture presets such as walls with openings, floor tiles, ceiling panels, stairs, railings, and facades.
• List procedural asset categories, presets, params, and examples.
• Create a composed furniture set scene.
• Create reusable room layout presets.
• List local model, texture, and reference assets.
• Maintain and search a local asset manifest with paths, tags, license/source notes, previews, and scale hints.
• Fit and place imported assets inside target bounds.
• Inspect current scene objects before editing.
• Move, rotate, scale, and resize named scene objects.
• Duplicate and arrange repeated objects.
• Add simple object keyframe animations.
• Apply draft, preview, and final render presets.
• Add reference images as textured planes for side-by-side modeling.
• Apply user-provided image textures to Blender objects.
• Create approximate scenes from structured reference-image plans.
• Import local .glb, .gltf, .fbx, and .obj assets.
• Export scenes/models to .glb and .obj.
• Render the current scene to PNG.
• Save the current scene to .blend.
• Inspect armatures and bone names.
• Use a development-only reload button to refresh add-on code without reinstalling.

Requirements

• Blender 3.6 or newer.
• Python available from your terminal.
• Codex is optional. The bridge can be used directly from a terminal.

Project Layout

codex-blender/
  .codex-plugin/plugin.json
  .mcp.json
  blender_addon/codex_blender_addon.py
  bridge/codex_blender_bridge.py
  scripts/codex_blender_mcp.py
  skills/blender/SKILL.md
  examples/
  assets/models/
  renders/
  scenes/

Use these folders by convention:

  assets/models/  3D input assets
  exports/        generated model exports
  renders/        generated PNG renders
  scenes/         generated .blend files

exports/, renders/, and scenes/ are ignored by Git.

Stable JSON commands live directly under examples/ and are covered by scripts/validate_project.py. One-off local experiments can be kept in examples/dev/, which is ignored by Git except for its README.

Stable reference images used by examples or docs live directly under assets/references/. One-off visual references can be kept in assets/references/dev/, which is ignored by Git except for its README.

Install The Blender Add-On

From Source

1. Open Blender.
2. Go to Edit > Preferences > Add-ons > Install.
3. Select:

blender_addon/codex_blender_addon.py

1. Enable Codex Blender Bridge.
2. In the 3D Viewport, press N to open the sidebar.
3. Open the Codex tab.
4. Click Start Bridge.

From ZIP

Download the latest add-on ZIP from GitHub Releases:

https://github.com/bestmaa/codex-blender/releases

Download the current versioned ZIP, for example:

codex_blender_addon_v1.7.3.zip

Or build it locally:

Build an installable ZIP:

python scripts\package_addon.py

Then install the generated ZIP from dist/ in Blender:

Edit > Preferences > Add-ons > Install

Check that the bridge is running:

Invoke-RestMethod -Uri http://127.0.0.1:8765/health

Expected response:

{
  "ok": true,
  "message": "Codex Blender Bridge is healthy."
}

First Run

1. Install and enable the Blender add-on.
2. Click Start Bridge in Blender's Codex sidebar tab.
3. Open a terminal in this project folder.
4. Run a health check.
5. Run one scene command.
6. Render or save the result.

Invoke-RestMethod -Uri http://127.0.0.1:8765/health
python bridge\codex_blender_bridge.py examples\create_room.json
python bridge\codex_blender_bridge.py examples\render_scene.json

Use From Terminal

Run commands from the project folder.

For a complete smoke test, see:

docs/quickstart-demo.md

When Blender is running, selected examples can also be tested with:

python scripts\smoke_test_bridge.py
python scripts\smoke_test_blendermcp.py

For image/reference matching, see:

docs/reference-workflow.md

For the stable JSON command schema, see:

docs/commands.md

For MCP tool coverage and raw-command notes, see:

docs/mcp-tools.md

For BlenderMCP compatibility planning, see:

docs/blendermcp-compatibility.md

For common local setup and runtime issues, see:

docs/troubleshooting.md

For Windows, WSL, UNC, and PowerShell path rules, see:

docs/windows-paths.md

Common Commands

python bridge\codex_blender_bridge.py examples\create_table_model.json
python bridge\codex_blender_bridge.py examples\create_outdoor_scene.json
python bridge\codex_blender_bridge.py examples\render_outdoor_scene.json
python bridge\codex_blender_bridge.py examples\create_primitive_library.json
python bridge\codex_blender_bridge.py examples\create_furniture_presets.json
python bridge\codex_blender_bridge.py examples\create_architecture_presets.json
python bridge\codex_blender_bridge.py examples\list_procedural_catalog.json
python bridge\codex_blender_bridge.py examples\search_assets.json
python bridge\codex_blender_bridge.py examples\import_asset_from_library.json
python bridge\codex_blender_bridge.py examples\create_furniture_set.json
python bridge\codex_blender_bridge.py examples\add_reference_image.json
python bridge\codex_blender_bridge.py examples\setup_compare_view.json
python bridge\codex_blender_bridge.py examples\set_render_preset.json
python bridge\codex_blender_bridge.py examples\render_scene.json
python bridge\codex_blender_bridge.py examples\save_blend.json

For release ZIP packaging, see:

docs/release-packaging.md

For included demo assets, see:

docs/demo-assets.md

For the local asset manifest format, see:

docs/asset-library.md

For the provider-neutral image-to-3D integration plan, see:

docs/image-to-3d.md

For beta release notes, see:

docs/beta-release-notes.md

For draft v1 release notes, see:

docs/release-notes-v1.md

For practical limitations and expectations, see:

docs/known-limitations.md

For the final smoke test matrix, see:

docs/smoke-test-matrix.md

For the final new-user walkthrough, see:

docs/final-user-walkthrough.md

For Windows path and PowerShell quoting examples, see:

docs/windows-paths.md

Create a starter room:

python bridge\codex_blender_bridge.py examples\create_room.json

Create an outdoor road scene:

python bridge\codex_blender_bridge.py examples\create_outdoor_scene.json
python bridge\codex_blender_bridge.py examples\render_outdoor_scene.json

Create a modern table model:

python bridge\codex_blender_bridge.py examples\create_table_model.json

Create a procedural primitive sample scene:

python bridge\codex_blender_bridge.py examples\create_primitive_library.json

Create procedural furniture presets:

python bridge\codex_blender_bridge.py examples\create_furniture_presets.json

Create procedural architecture presets:

python bridge\codex_blender_bridge.py examples\create_architecture_presets.json

List procedural catalog:

python bridge\codex_blender_bridge.py examples\list_procedural_catalog.json

Create a modern chair model:

python bridge\codex_blender_bridge.py examples\create_chair_model.json

Create a modern sofa model:

python bridge\codex_blender_bridge.py examples\create_sofa_model.json

Create an indoor plant model:

python bridge\codex_blender_bridge.py examples\create_plant_model.json

Create a lamp model:

python bridge\codex_blender_bridge.py examples\create_lamp_model.json

Create a furniture set scene:

python bridge\codex_blender_bridge.py examples\create_furniture_set.json

Create a room layout preset:

python bridge\codex_blender_bridge.py examples\create_room_layout.json

List local assets:

python bridge\codex_blender_bridge.py examples\list_assets.json
python bridge\codex_blender_bridge.py examples\search_assets.json
python bridge\codex_blender_bridge.py examples\import_asset_from_library.json

Fit the sample imported asset:

python bridge\codex_blender_bridge.py examples\fit_sample_asset.json

Inspect the current scene:

python bridge\codex_blender_bridge.py examples\inspect_scene.json

Transform the table top:

python bridge\codex_blender_bridge.py examples\transform_tabletop.json

Duplicate a table leg:

python bridge\codex_blender_bridge.py examples\duplicate_table_leg.json

Animate the table top:

python bridge\codex_blender_bridge.py examples\animate_tabletop.json

Apply a render preset:

python bridge\codex_blender_bridge.py examples\set_render_preset.json

Add a reference image plane:

python bridge\codex_blender_bridge.py examples\add_reference_image.json

Apply an image texture to an object:

python bridge\codex_blender_bridge.py examples\apply_table_texture.json

Apply a scaled image texture to an object:

python bridge\codex_blender_bridge.py examples\apply_scaled_wood_texture.json

Apply a multi-map texture material:

python bridge\codex_blender_bridge.py examples\apply_multimap_wood_texture.json

Apply a built-in material preset:

python bridge\codex_blender_bridge.py examples\apply_material_preset.json

Apply a reusable material recipe:

python bridge\codex_blender_bridge.py examples\apply_material_recipe.json

Set up a reference camera:

python bridge\codex_blender_bridge.py examples\setup_reference_camera.json

Set up a side-by-side compare view:

python bridge\codex_blender_bridge.py examples\setup_compare_view.json

Export the current scene to GLB:

python bridge\codex_blender_bridge.py examples\export_table_glb.json

Export the current scene to OBJ:

python bridge\codex_blender_bridge.py examples\export_table_obj.json

Import a local asset:

python bridge\codex_blender_bridge.py examples\import_asset.json

Render the current scene:

python bridge\codex_blender_bridge.py examples\render_scene.json

Save the current scene:

python bridge\codex_blender_bridge.py examples\save_blend.json

Inspect rigs:

python bridge\codex_blender_bridge.py examples\inspect_rig.json

Validate The Project

Run local checks without launching Blender:

python scripts\validate_project.py

Example Commands

Create room:

{
  "action": "create_room",
  "params": {
    "style": "modern_neon"
  }
}

Create outdoor scene:

{
  "action": "create_outdoor_scene",
  "params": {
    "road_length": 32,
    "road_width": 5,
    "tree_count": 12,
    "street_light_count": 6,
    "style": "clean_suburban"
  }
}

Create table model:

{
  "action": "create_table_model",
  "params": {
    "length": 3.6,
    "width": 2.0,
    "height": 1.55,
    "top_thickness": 0.24,
    "corner_roundness": 0.14,
    "include_grain": true,
    "wood_color": [0.78, 0.47, 0.25, 1],
    "style": "modern_wood"
  }
}

Create chair model:

{
  "action": "create_chair_model",
  "params": {
    "width": 1.35,
    "depth": 1.25,
    "height": 2.25,
    "seat_height": 0.95,
    "cushion_thickness": 0.18,
    "wood_color": [0.72, 0.45, 0.25, 1],
    "fabric_color": [0.34, 0.48, 0.56, 1],
    "style": "modern_wood"
  }
}

Create sofa model:

{
  "action": "create_sofa_model",
  "params": {
    "width": 3.2,
    "depth": 1.35,
    "height": 1.55,
    "seat_height": 0.62,
    "cushion_count": 3,
    "cushion_gap": 0.035,
    "fabric_color": [0.42, 0.54, 0.62, 1],
    "leg_color": [0.42, 0.25, 0.14, 1],
    "style": "modern_couch"
  }
}

Create plant model:

{
  "action": "create_plant_model",
  "params": {
    "height": 2.1,
    "pot_radius": 0.42,
    "pot_height": 0.58,
    "leaf_count": 18,
    "stem_count": 5,
    "leaf_color": [0.20, 0.55, 0.34, 1],
    "pot_color": [0.70, 0.62, 0.52, 1],
    "style": "indoor_potted"
  }
}

Create lamp model:

{
  "action": "create_lamp_model",
  "params": {
    "lamp_type": "floor",
    "height": 2.4,
    "shade_radius": 0.38,
    "power": 520,
    "metal_color": [0.23, 0.23, 0.22, 1],
    "shade_color": [0.95, 0.86, 0.68, 1],
    "style": "warm_modern"
  }
}

Create furniture set:

{
  "action": "create_furniture_set",
  "params": {
    "table_length": 3.2,
    "table_width": 1.55,
    "chair_count": 4,
    "include_plant": true,
    "include_lamp": true,
    "style": "compact_dining"
  }
}

Create room layout:

{
  "action": "create_room_layout",
  "params": {
    "preset": "living_room",
    "style": "clean_modern"
  }
}

List assets:

{
  "action": "list_assets",
  "params": {
    "type": "texture",
    "extension": "png"
  }
}

Fit o

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bestmaa
• Source: bestmaa/codex-blender
• License: MIT

Install and usage instructions live in the source repository linked above.