blender-chatgpt-mcp

Control a local Blender scene from Codex or ChatGPT through MCP.

This project lets an AI assistant inspect your open Blender scene, create objects, edit materials, set cameras and lights, render previews, and save safe copies of your .blend file. Everything runs on your own computer.

Read This First

• You do not need an OpenAI API key.

• Do not put OPENAI_API_KEY in this project.

• Do not put any ChatGPT, Codex, or OpenAI account token in this project.

• The only token this project uses is BLENDER_BRIDGE_TOKEN. It is a local password between the MCP server and Blender on your own computer.

• The default setup uses 127.0.0.1, which means your own machine only.

For Codex, sign in with ChatGPT so usage follows your Codex/ChatGPT plan quota. This project does not call the OpenAI Platform API.

Related MCP server: blend-ai

What You Are Installing

There are two local pieces:

1. A Blender add-on that opens a private local bridge inside Blender.

2. A small Node.js MCP server that Codex or ChatGPT can talk to.

The path looks like this:

Codex
  -> local MCP server at http://127.0.0.1:3000/mcp
  -> local Blender bridge at http://127.0.0.1:8765
  -> Blender

Optional ChatGPT connector setups can use Secure MCP Tunnel, but Codex local setup does not need a tunnel.

How This Relates To Blender Lab MCP

Blender also has a Blender Lab MCP Server:

https://www.blender.org/lab/mcp-server/

That project is a powerful general-purpose MCP server for exploring Blender through the Python API. Blender's own page warns that it can execute LLM-generated code in Blender without guards.

This project is intentionally more conservative. It exposes fixed tools with typed inputs, bounded file access, localhost-only defaults, and no arbitrary Python or shell execution. Use Blender Lab MCP when you want broad Python API exploration. Use this project when you want a safer Codex-oriented local bridge for common scene operations.

What You Need

Install these first:

• Blender 5.1 or newer

• Node.js 20 or newer

• Codex CLI or Codex IDE extension, signed in with ChatGPT

This project targets Blender 5.1 or newer and is tested with Blender 5.1.2. Older Blender 3.x and 4.x releases are not supported.

On macOS, Blender is usually installed at /Applications/Blender.app. The helper scripts can find that automatically.

Download This Project

If you are using Git:

git clone https://github.com/bakaroart/blender-chatgpt-mcp.git
cd blender-chatgpt-mcp

If you downloaded a ZIP from GitHub, unzip it, then open Terminal in the unzipped folder.

Step 1: Install Project Dependencies

Run this once:

npm install

Then build the server and package the Blender add-on:

npm run build
npm run package:addon

This creates:

dist/blender_chatgpt_bridge.zip

Step 2: Install The Blender Add-On

Open Blender.

In Blender:

1. Open Preferences.

2. Go to Add-ons.

3. Choose Install from Disk.

4. Select dist/blender_chatgpt_bridge.zip.

5. Enable Blender MCP Bridge.

Then open the add-on preferences:

1. Set Project Root to this project folder.

2. Click Generate Token.

3. Click Copy Token.

Keep Blender open.

Step 3: Create Your Local .env File

In the project folder, copy the example environment file:

cp .env.example .env

Open .env in any text editor. On macOS, this works:

open -e .env

Find this line:

BLENDER_BRIDGE_TOKEN=replace-with-token-generated-in-blender

Replace replace-with-token-generated-in-blender with the token you copied from Blender.

Do not add OPENAI_API_KEY. Do not add any OpenAI account secret.

Save the file.

Step 4: Start The Blender Bridge

You can start the bridge from Blender or from Terminal.

Option A: Start From Blender

In Blender:

1. Open the 3D View sidebar.

2. Open the MCP Bridge tab.

3. Click Start MCP Bridge.

Option B: Start From Terminal

On macOS, you can also run:

npm run bridge:blender

This opens Blender and starts the bridge using the token in .env.

Step 5: Start The MCP Server

Open a second Terminal window in the project folder and run:

npm run start

Leave this Terminal window open while you use Blender from Codex or ChatGPT.

Step 6: Check That Everything Is Connected

Open another Terminal window and run:

curl http://127.0.0.1:3000/healthz
curl http://127.0.0.1:3000/readyz
curl http://127.0.0.1:8765/healthz

Good signs:

• /healthz says the MCP server is running.

• /readyz says the Blender bridge is available and authenticated.

• Blender bridge /healthz says the bridge is running.

If /readyz says BRIDGE_UNAVAILABLE, start the bridge in Blender.

If /readyz says authentication failed, copy the token from Blender into .env again and restart npm run start.

Step 7: Connect Codex

This repository includes a project-scoped Codex config at:

.codex/config.toml

It points Codex to:

http://127.0.0.1:3000/mcp

Start a new Codex session in this project folder so Codex loads the config. In the Codex terminal UI, run:

/mcp

You should see the Blender MCP server listed.

If Codex does not load the project config, copy this into your Codex config.toml:

[mcp_servers.blender_chatgpt]
url = "http://127.0.0.1:3000/mcp"
startup_timeout_sec = 20
tool_timeout_sec = 120
default_tools_approval_mode = "prompt"

For many Codex installs, the user config file is:

~/.codex/config.toml

Step 8: Try It In Codex

With Blender open, the Blender bridge running, and npm run start still running, ask Codex something like:

Use the Blender MCP tools to inspect the scene, create a blue cube, add a camera and light, render a preview, and save a copy.

Keep tool approval set to prompt mode at first. This gives you a chance to review actions before Codex changes Blender.

Optional: Run The Built-In Demo

After Blender and the MCP server are running:

npm run demo:mcp

For a larger scene:

npm run showcase:mcp

These commands use the same MCP tools Codex uses. They create objects, render a preview, and save a .blend copy under dist/.

Optional: Use With ChatGPT Connector

Codex local setup is the simplest path. ChatGPT connector setup is optional and requires whatever ChatGPT developer/custom connector capability is available to your account or workspace.

For ChatGPT connector setups, forward this local MCP endpoint through Secure MCP Tunnel:

http://127.0.0.1:3000/mcp

Then create or refresh the ChatGPT connector and review the exposed Blender tools. Product UI labels can change, so use the current official ChatGPT connector instructions for your account.

What The Tools Can Do

The MCP server exposes fixed, typed Blender tools for:

• Getting Blender status and scene summaries

• Creating primitives like cubes, planes, spheres, cylinders, cones, and torus meshes

• Duplicating, renaming, transforming, hiding, and deleting exact object names

• Creating and assigning materials

• Creating and updating lights

• Creating or updating cameras

• Setting world background

• Rendering bounded previews

• Saving safe .blend copies under the configured project root

The server does not expose arbitrary Python execution, shell execution, unrestricted file access, generic Blender operator dispatch, or wildcard object deletion.

Stopping Everything

To stop the MCP server, press Ctrl+C in the Terminal window running:

npm run start

To stop the Blender bridge, either click Stop MCP Bridge in Blender or close Blender.

Updating Later

After pulling a new version from GitHub:

npm install
npm run build
npm run package:addon

Then reinstall dist/blender_chatgpt_bridge.zip in Blender.

Troubleshooting

npm install fails

Make sure Node.js 20 or newer is installed:

node --version

Also make sure you are connected to the internet, because npm install downloads packages from the public npm registry.

If npm install was interrupted and a later run mentions ENOTEMPTY, remove the half-installed dependency folder and run it again:

rm -rf node_modules
npm install

In restricted Codex or sandboxed terminal environments, npm might not be allowed to write to the normal ~/.npm cache folder. In that case, keep the cache inside the project folder:

npm install --cache ./.npm-cache

Blender cannot be found

On macOS, install Blender in /Applications. If Blender is somewhere else, set BLENDER_BIN to the Blender executable path before running helper scripts.

npm run test:blender crashes Blender

The Blender smoke test is mainly for contributors. If Blender exits before printing any SMOKE TEST FAILED message and writes a blender.crash.txt file, first check whether Blender itself can run in background mode:

/Applications/Blender.app/Contents/MacOS/Blender --background --factory-startup --python-expr 'print("Blender background mode works")'

If that command also crashes, it is a local Blender/background-mode issue rather than an MCP bridge setup issue. Open Blender normally and continue with the add-on setup from Step 2.

/readyz says BRIDGE_UNAVAILABLE

Blender is not reachable. Open Blender and start the MCP Bridge from the sidebar, or run:

npm run bridge:blender

/readyz says authentication failed

The token in .env does not match Blender. Generate or copy the token from Blender again, paste it into .env, save the file, and restart:

npm run start

Codex does not show the Blender server

Restart Codex in this project folder, then run:

/mcp

If it still does not appear, copy the MCP config block from Step 7 into ~/.codex/config.toml.

Preview rendering fails

Try a smaller render size or fewer samples. The preview tool intentionally has size and timeout limits.

Development Commands

For contributors:

npm run lint
npm run typecheck
npm test
npm run test:integration
npm run check

Run Blender smoke tests when Blender is installed:

npm run test:blender

If You Fork Or Contribute

Normal users do not need to do anything in this section.

If you fork this repository, open a pull request, or publish your own changes, keep private local files out of GitHub. Check that these files and folders are not committed:

• .env

• dist/

• node_modules/

• .npm-cache/

• rendered previews

• personal .blend outputs

• Codex or ChatGPT auth files

• OpenAI API keys or access tokens

The included .gitignore already ignores the common local outputs, but it is still worth checking before you push.

More Documentation

• Codex setup

• Blender add-on installation

• Tool reference

• Architecture

• Security details

• Troubleshooting