blender-mcp

An MCP server that lets AI coding agents control Blender. 26 tools bridge to the Blender MCP add-on you already have installed (TCP port 9876). There’s also an Agent Skill (SKILL.md) that teaches an agent how to actually use them well.

Works with anything that speaks MCP + Agent Skills: Codex CLI, Grok Build, Cursor, Antigravity, Claude Code, probably whatever else you’re running too.

CLI-variant tools launch a headless background Blender to inspect .blend files on disk without touching your open session.

Prerequisites

1. Blender 5.1+, with the official Blender Lab MCP extension installed and running. This is the first-party extension from blender.org/lab/mcp-server. In Blender, go to Edit > Preferences > Extensions > Get Extensions, search “MCP”, install it, enable it, then click “Start MCP Server” in the extension’s preferences panel (default localhost:9876).

   Note: there are other, older community Blender+MCP add-ons floating around (different protocol, different port, different install path under the legacy Add-ons system). This repo talks to the official Lab extension specifically. If your setup doesn’t match the steps above, this server won’t be able to connect.

2. Python 3.10+. Install the mcp package for whichever Python your agent will launch this server with:

   pip install mcp
   

3. Clone this repo somewhere on disk. Setup below refers to /blender_mcp_server.py. Swap in your actual clone path.

Setup per platform

Every platform needs the same two things done: register blender_mcp_server.py as an MCP server, then make skill/blender-mcp/SKILL.md discoverable so the agent knows how to use it. No skill support on your platform? Skip that part. The MCP tools still work, you just lose the extra guidance.

Codex CLI

Add to config.toml (default ~/.codex/config.toml; check codex doctor for CODEX_HOME if you’ve customized it):

[mcp_servers.blender]
command = "python"
args = ["/blender_mcp_server.py"]

Copy the skill so Codex can discover it:

/skills/blender-mcp/SKILL.md

Verify: codex mcp list should show blender. codex exec "Which skill do you have for Blender work?" should mention blender-mcp.

Grok Build CLI

grok mcp add blender python -- /blender_mcp_server.py

Copy the skill to ~/.agents/skills/blender-mcp/SKILL.md (the shared convention below), or drop it in .agents/skills/blender-mcp/SKILL.md inside a specific repo for project scope.

Verify: grok mcp list and grok inspect should both show blender-mcp.

Cursor

Add to .cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["/blender_mcp_server.py"]
    }
  }
}

Copy the skill folder into .cursor/skills/blender-mcp/ in your project. Cursor picks it up next session.

Antigravity (CLI, IDE, Antigravity 2.0)

Add to ~/.gemini/config/mcp_config.json:

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["/blender_mcp_server.py"]
    }
  }
}

Copy the skill to ~/.gemini/config/skills/blender-mcp/. It’s the only path all three Antigravity flavors (CLI, IDE, 2.0) recognize. Project-scoped skills work too, at .agents/skills/blender-mcp/ inside a workspace.

Any other Agent Skills / MCP-compatible platform

SKILL.md is an open, cross-agent standard: Claude Code, Codex, Cursor, and Antigravity all read the same format. Copying skill/blender-mcp/ as-is into whatever skills directory your agent reads usually just works. For MCP registration, look for a mcpServers (JSON) or [mcp_servers.*] (TOML) block and add:

command: python
args: ["/blender_mcp_server.py"]

Try .agents/skills/ (project-level) first if your platform isn’t listed above. Several tools already read it as a shared convention.

Usage

Once the Blender extension’s server is running and at least one platform above is registered, just ask your agent to do Blender things. The skill kicks in on its own. You don’t need to mention it by name:

• “Add a cube to the scene, scale it to 2m, and tell me its dimensions.”
• “Take a screenshot of the viewport.”
• “Export the selected object as GLB to ~/Desktop/model.glb.”

SKILL.md pushes the agent to inspect the scene first (blender_get_objects_summary), make one focused change at a time, then verify with real numbers instead of just eyeballing a screenshot. Want a specific tool directly, no skill guidance involved? Call it by name, e.g. blender_execute_python with raw bpy code.

Troubleshooting

Codex desktop app can’t launch the server on Windows. This is different from a “could not connect to Blender at localhost:9876” error. That one just means Blender isn’t open yet. This one means the Python process never started at all.

Codex ships two things on Windows: a plain CLI executable that inherits your normal terminal PATH, and a Store/MSIX-packaged desktop app (OpenAI.Codex, visible via Get-AppxPackage). The packaged app’s environment can be more restricted than a terminal session, so it may fail to find a working python even though the same command works fine through the terminal, Codex CLI, or Grok Build CLI.

Fastest fix: install uv and let it provide a Python the packaged app can reliably find:

uv python install

Still not found? Point the MCP config’s command directly at the Python uv installed instead of the bare python name.

Tools (26)

Read-only (19):

• blender_get_blendfile_datablocks_summary (+ _cli)
• blender_get_blendfile_missing_files_summary (+ _cli)
• blender_get_blendfile_linked_libraries_summary (+ _cli)
• blender_get_blendfile_path_info_summary (+ _cli)
• blender_get_blendfile_usage_summary (+ _cli)
• blender_get_objects_summary
• blender_get_object_detail_summary
• blender_get_python_api_docs
• blender_get_window_screenshot (returns inline PNG)
• blender_get_area_screenshot (returns inline PNG)
• blender_get_screenshot_as_json
• blender_render_viewport_to_path
• blender_search_api_docs
• blender_search_user_manual

Write / state-changing (7):

• blender_execute_python (the power tool - arbitrary bpy code)
• blender_execute_python_cli (arbitrary code on a .blend file, headless)
• blender_switch_workspace
• blender_switch_matching_workspace
• blender_focus_object
• blender_focus_object_data
• blender_render_thumbnail_to_path

Conventions

• Interactive tools: executed code assigns a JSON-serializable dict to result.
• CLI tools: executed code assigns the dict to summary; changes to the .blend file are DISCARDED unless the code calls bpy.ops.wm.save_mainfile().
• CLI tools auto-detect blender.exe from the running instance; override with the BLENDER_BINARY environment variable if Blender is closed.

Env vars

BLENDER_MCP_HOST (default localhost), BLENDER_MCP_PORT (default 9876), BLENDER_MCP_TIMEOUT (default 120 s), BLENDER_BINARY (path to blender.exe).

Credits

The 26-tool surface here is designed in the spirit of ahujasid/blender-mcp, the original, widely-used Blender+LLM connector. This is not a fork and shares no code with it: it talks to the different, official Blender Lab MCP extension’s protocol (null-byte delimited JSON, port 9876) instead of that project’s community add-on protocol. Credit for the tool-surface idea; the protocol and implementation here are independent.

Notes

• Requests are short-lived one-shot connections. Multiple agents can share the same Blender instance. Just don’t fire heavy operations from more than one at the same instant.
• Screenshot tools return images inline as MCP image content. Clients that render images can literally see your viewport.