Skip to content
Conduit

mcp server

blender-codex-mcp

Connect Codex to Blender through a local MCP server and Blender addon.

webita/blender-codex-mcpcommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "blender-codex-mcp": {
      "command": "uvx",
      "args": [
        "blender-codex-mcp"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 25, 2026

Blender Codex MCP

Blender Codex MCP connects Codex to Blender through the Model Context Protocol.

  • Blender runs a local socket addon on localhost:9876 by default.
  • Codex runs an MCP server from this repository.
  • The MCP server forwards tool calls into Blender.

This fork is focused on practical 3D work with Codex: scene inspection, viewport screenshots, Python execution inside Blender, and optional asset/model integrations.

Quick Install

  1. Clone this repo.
git clone https://github.com/webita/blender-codex-mcp.git
cd blender-codex-mcp
  1. Install addon.py in Blender.
  2. Enable the addon and click Connect to MCP server in the Blender sidebar.
  3. Add the MCP config below to ~/.codex/config.toml.
  4. Restart Codex and ask it to inspect Blender.
[mcp_servers.blender]
command = "uv"
args = [
  "--directory",
  "/absolute/path/to/blender-codex-mcp",
  "run",
  "blender-codex-mcp"
]

[mcp_servers.blender.env]
BLENDER_HOST = "localhost"
BLENDER_PORT = "9876"
DISABLE_TELEMETRY = "true"

Useful first prompt:

Inspect the open Blender scene and take a viewport screenshot.

Note: Codex does not currently provide a public third-party plugin marketplace. This repository is meant to be installed from GitHub as an MCP server. A local Codex plugin scaffold is included for future/plugin-based workflows.

MCP Server Vs Codex Plugin

These are related, but not the same thing.

  • This repository is primarily an MCP server plus Blender addon.
  • An MCP server exposes tools that Codex can call.
  • A Codex plugin can be used as a packaging/distribution layer to make installation, discovery, and setup easier.

So yes: this project can also become a Codex plugin.

The cleanest public setup is usually:

  1. keep this repo as the source of truth for the Blender addon and MCP server
  2. optionally publish a Codex plugin that helps users install or configure the MCP server

In other words:

  • the MCP server is the engine
  • the plugin can be the smoother installation experience

This repository now also includes a repo-local plugin scaffold at plugins/blender-codex-connector, so you can publish the MCP project and evolve a Codex plugin alongside it without splitting the codebase yet.

Why This Project Exists

Most AI coding agents can write Blender Python, but they cannot see or control a live Blender scene well enough to iterate safely.

This project solves that by giving Codex a bridge to:

  • inspect the current scene
  • query objects
  • capture viewport screenshots
  • execute Blender Python step by step
  • optionally search/import Poly Haven, Sketchfab, Hyper3D Rodin, and Hunyuan3D content

The result is a much tighter loop for:

  • product renders
  • architectural/technical mockups
  • scene cleanup and organization
  • scripted modeling
  • export-ready 3D preparation for the web

Features

  • get_scene_info: inspect the current Blender scene
  • get_object_info: inspect a specific object
  • get_viewport_screenshot: capture the current viewport for visual feedback
  • execute_blender_code: run Python inside Blender
  • blender_health_check: verify that Blender and the socket bridge are reachable
  • sync_camera_to_viewport: copy the current 3D viewport view into the active scene camera
  • export_glb: export the scene or selected objects as .glb
  • optional asset integrations from Poly Haven and Sketchfab
  • optional AI generation integrations through Hyper3D Rodin and Hunyuan3D

Repository Layout

Requirements

  • Blender installed locally
  • Codex desktop or another MCP-compatible Codex runtime
  • uv installed locally
  • Python 3.10+

Install The Blender Addon

  1. Open Blender.
  2. Go to Edit > Preferences > Add-ons.
  3. Click Install....
  4. Select addon.py.
  5. Enable Interface: Blender Codex MCP.
  6. In the 3D viewport, press N, open the BlenderCodexMCP tab, and click Connect to MCP server.

By default the addon listens on localhost:9876.

Configure Codex

Add this to ~/.codex/config.toml:

[mcp_servers.blender]
command = "uv"
args = [
  "--directory",
  "/absolute/path/to/blender-codex-mcp",
  "run",
  "blender-codex-mcp"
]

[mcp_servers.blender.env]
BLENDER_HOST = "localhost"
BLENDER_PORT = "9876"
DISABLE_TELEMETRY = "true"

Then restart Codex.

Only one MCP server should connect to the Blender addon at a time.

Codex Plugin Scaffold

If you want to ship this as a Codex plugin too, start from:

The current scaffold is intentionally simple:

  • plugin metadata lives in the plugin folder
  • the plugin points back to this repo's MCP server with uv
  • you can fill in public URLs, screenshots, and marketplace details when you publish

At the moment, treat this as experimental packaging. The recommended public install path is still the manual MCP setup from GitHub.

Quick Start

  1. Open Blender.
  2. Enable the addon.
  3. Click Connect to MCP server in Blender.
  4. Restart or reopen Codex so it loads the MCP server.
  5. Ask Codex to inspect the scene before making changes.

Useful first prompts:

  • Controlla la scena Blender e dimmi cosa contiene.
  • Fai uno screenshot della viewport e dimmi se la camera è corretta.
  • Sincronizza la camera alla vista attuale e poi fammi uno screenshot.
  • Crea una camera isometrica e una luce studio morbida.
  • Scrivi uno script Blender pulito per organizzare gli oggetti in collezioni.
  • Prepara il modello per export GLB per il web.

Recommended Workflow

For best results, ask Codex to work in small steps:

  1. inspect the scene
  2. make one structural change
  3. capture a viewport screenshot
  4. refine
  5. prepare export

This is safer than asking for a huge one-shot scene rewrite.

Best Practices

  • Save the .blend file before large operations.
  • Ask for viewport screenshots often.
  • Prefer incremental modeling over giant code dumps.
  • Keep the scene organized in collections if you plan to export for the web.
  • For web export, keep materials simple and avoid unnecessary geometry.
  • Use .glb for distribution unless you have a specific reason to export another format.

Export For The Web

Short version:

  1. prepare the model in Blender
  2. export as .glb
  3. upload the .glb
  4. embed it in WordPress with a WebGL viewer

Full workflow:

Examples

This example is intentionally generic and useful for many scenes:

  • center geometry
  • place the model on the ground plane
  • apply simple base materials
  • create a clean default camera
  • add basic lights for screenshots and GLB export prep

Troubleshooting

Codex cannot connect to Blender

  • Make sure Blender is open.
  • Make sure the addon is enabled.
  • Make sure the addon says it is running on port 9876.
  • Make sure your Codex config points to the correct repo path.
  • Restart Codex after editing ~/.codex/config.toml.

The MCP server loads but tools fail

  • Check that Blender is still open.
  • Check that no second MCP server is already attached.
  • Check whether the addon and repo version match.

Viewport screenshots fail

  • Make sure a VIEW_3D area exists in the active screen layout.
  • Switch Blender back to a normal layout with a visible 3D viewport.

Telemetry questions

Telemetry is conservative by default in this fork.

  • Recommended for local/private use: DISABLE_TELEMETRY=true
  • Internal config also supports BLENDER_MCP_TELEMETRY_ENABLED

If you publish publicly, document telemetry behavior clearly in GitHub and in the video.

FAQ

Is this a one-click Codex plugin?

Not yet. Today the reliable public install path is GitHub plus manual MCP configuration. The repo includes an experimental Codex plugin scaffold, but there is currently no public third-party Codex plugin marketplace for one-click discovery and install.

Does Blender need to stay open?

Yes. The MCP server talks to the Blender addon running inside a live Blender session.

Does this install Blender automatically?

No. Users install Blender separately, then install addon.py in Blender.

Can Codex see what it is doing in Blender?

It can inspect scene data and request viewport screenshots through the MCP tools. That feedback loop is the main reason this bridge is useful.

Can I use this for web exports?

Yes. Use export_glb or Blender's built-in export workflow, then embed the .glb with a WebGL viewer. See docs/WORDPRESS_EMBED.md.

What I Would Improve Before Public Launch

The project is already publishable, but these would make it stronger:

  1. Add a short demo GIF or video in the README.
  2. Add a docs/ folder with setup, troubleshooting, and export examples.
  3. Add a release section with tested versions of Blender and Codex.
  4. Add a small FAQ.

I have added the docs pieces that help most immediately for GitHub and YouTube.

Known Limitations

  • This bridge depends on a live Blender session.
  • The addon uses a local socket transport; if Blender is closed, tools fail.
  • execute_blender_code is powerful and should be used carefully.
  • Viewport capture depends on a valid 3D viewport being visible in Blender.

Safety Notes

execute_blender_code can run arbitrary Python inside Blender.

Before large operations:

  • save your file
  • work incrementally
  • verify with screenshots

License

MIT. See LICENSE.

Credits

Blender Codex MCP is a Codex-focused fork adapted by Webita - Giorgio Sanna.

Thanks to the original open-source Blender MCP project for the base Blender socket and MCP workflow.

↑↓ navigate openesc close