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.