Add to your config file:

{
  "mcpServers": {
    "blender": {
      "command": "/absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server"
    }
  }
}

Replace the path with the actual location of your clone.

Register the server once:

codex mcp add blender -- /absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server

Verify with codex mcp list. Then start Codex from any directory — it launches the server automatically.

Point any MCP-compatible client at the server executable:

/absolute/path/to/blender-mcp-server/.venv/bin/blender-mcp-server

The server uses stdio transport. No additional flags are needed.

• "What objects are in my scene?"
• "Show me the transform of the Camera object"
• "List all materials in the file"

• "Create a sphere named 'Earth' at position [0, 0, 2] with size 3"
• "Add a cylinder at the origin, then scale it to [0.5, 0.5, 4] to make a tall pillar"
• "Create 5 cubes in a row spaced 3 units apart"

• "Create a red material and assign it to the Cube"
• "Make a material called 'Ocean' with color [0.0, 0.3, 0.8] and assign it to the Sphere"
• "Change the color of 'RedMaterial' to orange"

• "Move the Cube up 2 units on the Z axis"
• "Rotate the Cylinder 45 degrees on the Z axis"
• "Scale the Sphere to [2, 2, 2]"

• "Render the scene at 1920×1080 and save it to /tmp/render.png"
• "Export the scene as a GLB file to /tmp/scene.glb"

• "Run this Blender Python: bpy.ops.mesh.primitive_monkey_add(location=(0,0,2))"
• "Execute the fluid_domain.py script from the library with resolution 128"
• "Start an async bake job for the fluid simulation and tell me the job ID"

• "Undo the last change"
• "Redo what was just undone"

The helper scripts in scripts/ connect directly to the Blender add-on on 127.0.0.1:9876, bypassing the MCP server entirely. Useful for verifying the add-on works:

python3 scripts/blender_scene_info.py
python3 scripts/blender_create_test_cube.py --name TestCube --x 0 --y 0 --z 1 --size 2
python3 scripts/blender_bridge_request.py scene.get_info
python3 scripts/blender_bridge_request.py object.translate --params '{"name":"TestCube","offset":[0,0,2]}'

All scripts accept --host, --port, and --timeout flags.

Run Blender without a GUI for automation:

blender -b --python your_script.py

Where your_script.py starts the MCP bridge:

import sys
sys.path.insert(0, "/path/to/blender-mcp-server")
from addon import CommandHandler, BlenderMCPServer

server = BlenderMCPServer()
server.start()

import socket
s = socket.socket()
s.bind(("127.0.0.1", 9877))
s.listen(1)
s.accept()  # Blocks until shutdown signal

Inline code — create a fluid domain:

{
  "tool": "blender_python_exec",
  "args": {
    "code": "import bpy\nbpy.ops.mesh.primitive_cube_add(size=4, location=(0,0,2))\ndomain = bpy.context.active_object\ndomain.name = 'FluidDomain'\nbpy.ops.object.modifier_add(type='FLUID')\ndomain.modifiers['Fluid'].fluid_type = 'DOMAIN'\nsettings = domain.modifiers['Fluid'].domain_settings\nsettings.domain_type = 'LIQUID'\nsettings.resolution_max = 64\n__result__ = {'domain': domain.name, 'resolution': 64}",
    "args": {"resolution": 64}
  }
}

Script file — set up colliders:

{
  "tool": "blender_python_exec",
  "args": {
    "script_path": "scripts/library/effector.py",
    "args": {
      "objects": ["Ground", "Building_01", "Building_02"],
      "effector_type": "COLLISION"
    }
  }
}

Async bake and poll:

{"tool": "blender_python_exec_async", "args": {"code": "import bpy\nbpy.ops.fluid.bake_all()\n__result__ = {'baked': True}", "timeout_seconds": 1800}}

→ {"job_id": "job-f8e2a1b3"}

{"tool": "blender_job_status", "args": {"job_id": "job-f8e2a1b3"}}