Content
# 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](https://www.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
`<repo>/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):
```toml
[mcp_servers.blender]
command = "python"
args = ["<repo>/blender_mcp_server.py"]
```
Copy the skill so Codex can discover it:
<CODEX_HOME>/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 -- <repo>/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):
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": ["<repo>/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`:
```json
{
"mcpServers": {
"blender": {
"command": "python",
"args": ["<repo>/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: ["<repo>/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](https://docs.astral.sh/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).
## 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.
