# Connect Blender 5.1+ to AI Agents via Official Blender MCP (tested)

lastVerified: 2026-10-17 · blender-mcp package from lab/blender_mcp · uv + MCP SDK

Wire Claude Code, Cursor, Codex, or other MCP clients to a running Blender session using the **official** Blender Lab MCP server (Blender Foundation / Blender Lab). Source: https://projects.blender.org/lab/blender_mcp · Docs: https://www.blender.org/lab/mcp-server/ · License: **GPL-3.0** (see repo LICENSE).

## Security (from official docs)

The MCP server can execute LLM-generated Python inside Blender with no sandbox. Official guidance: use a VM or a machine without sensitive files. Do not point this at production `.blend` files with secrets.

## Requirements

1. **Blender 5.1 or newer** with the Lab MCP add-on enabled (install from Blender Lab extensions: https://lab.blender.org/ or follow https://www.blender.org/lab/mcp-server/).
2. An MCP-capable client (Claude Code, Cursor, Codex, Windsurf, etc.).
3. The `blender-mcp` stdio (or HTTP) server process.

## Tested on this box (2026-10-17)

Blender GUI was **not** available here, so add-on + live scene tools were not end-to-end exercised. These steps **were** verified:

```bash
git clone https://projects.blender.org/lab/blender_mcp.git
cd blender_mcp/mcp
# Optional: uv venv && source .venv/bin/activate
uv pip install -e .
blender-mcp --help
# usage: blender-mcp [-h] [--transport {stdio,http}] [--host HOST] [--port PORT]
```

Package version in pyproject.toml at clone time: `1.0.2`. Installed MCP SDK `1.30.0`. Discovered tool modules include `execute_blender_code`, `get_objects_summary`, `get_python_api_docs`, `search_manual_docs`, viewport/screenshot helpers, and render-to-path tools.

## MCP client config (stdio + uv)

Replace the directory with your real clone path (clients often do not expand `$HOME`):

```json
{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/blender_mcp/mcp",
        "run",
        "blender-mcp"
      ]
    }
  }
}
```

Alternate install: `pip install git+https://projects.blender.org/lab/blender_mcp.git#subdirectory=mcp` then point `command` at `blender-mcp` on your PATH.

HTTP transport (local only): `blender-mcp --transport http --host 127.0.0.1 --port 8000`.

## After connect

1. Launch Blender 5.1+, enable the MCP add-on, confirm it is listening.
2. Start the client so it spawns `blender-mcp`.
3. Ask the agent to inspect the scene first (`get_objects_summary` / API docs) before any destructive edits.
4. Good first prompts (from Blender Lab demos): rename typo'd data-blocks; list objects using a material; find high-poly outliers relative to camera size.

## Attribution

Official project by Blender Lab / Blender Foundation. Curated setup notes and install verification by Index Scout (R Performance Marketing). Not affiliated with Blender. Always re-check https://www.blender.org/lab/mcp-server/ and the repo before production use. Last verified 2026-10-17.