Open-source MCP to use Blender with any LLM
Three steps: install uv, point your MCP client at the server, install the Blender addon.
1. Install uv
# macOS
brew install uv
# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Warning: Do not proceed before installing uv. Use the official installer — not
pip install uv.
2. Add the MCP server to your client
Claude Desktop — Settings → Developer → Edit Config{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["blender-mcp"]
}
}
}
claude mcp add blender uvx blender-mcp
codex mcp add blender -- uvx blender-mcp
See MCP Client Setup below for per-client instructions and one-click install buttons.
3. Install the Blender addon
uvx blender-mcp install-addon
Then in Blender: Edit → Preferences → Add-ons → enable Interface: MCP for Blender.
4. Connect
In Blender's 3D viewport, press N → open the MCP for Blender tab → click Start MCP Server. That's it — ask Claude to build something.
Note: Only run one instance of the MCP server (either Cursor or Claude Desktop), not both.
The system consists of two main components:
addon.py) — a Blender addon that creates a socket server within Blender to receive and execute commandssrc/blender_mcp/server.py) — a Python server that implements the Model Context Protocol and connects to the Blender addonmacOS
brew install uv
Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
Then add uv to the user path in Windows (you may need to restart Claude Desktop after):
$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")
Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
It lands in ~/.local/bin — open a new shell so it's on your PATH.
Otherwise, installation instructions are on their website: Install uv
On every OS, use uv's official installer above — not pip install uv, which may not create the uvx command and can hide uv inside an environment your client can't see.
Warning: Do not proceed before installing uv.
MCP clients started from a GUI (Claude Desktop, Cursor, VS Code from the Dock/Start menu) do not inherit your terminal's PATH, so a bare "command": "uvx" can fail with spawn uvx ENOENT even though uvx works in your terminal. If that happens:
which uvx (macOS/Linux) or where uvx (Windows) — and use it as "command", e.g. /opt/homebrew/bin/uvx or C:\Users\<you>\.local\bin\uvx.exe."command": "cmd", "args": ["/c", "uvx", "blender-mcp"].Avoid conda / pyenv / version conflicts.
uv chooses which Python runs the server. On machines with conda (auto-activated base), pyenv, or asdf — or with a newer CPython release that some dependencies do not have wheels for yet — uv can grab an interpreter that makes installation fail. Pin Python 3.11 and prefer uv-managed interpreters to avoid using whatever is on your PATH:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": ["--python", "3.11", "blender-mcp"],
"env": { "UV_PYTHON_PREFERENCE": "only-managed" }
}
}
}
--python 3.11 still satisfies this package's requires-python >=3.10, and UV_PYTHON_PREFERENCE=only-managed keeps uv from selecting conda, pyenv, asdf, or system Python first. (The repo's .python-version is only a hint for contributors and does not affect uvx.)
If a previous failed attempt keeps replaying after a fix, clear the cache:
uv cache clean blender-mcp && uvx --refresh blender-mcp
On locked-down machines you can skip uvx entirely with pipx, then point your client at the installed command:
pipx install blender-mcp
pipx ensurepath # then restart your shell / client
Use the resulting absolute path as "command" (find it with which blender-mcp / where blender-mcp) and omit args.
You can run the MCP server in a container instead of installing it. Blender itself still runs on your machine — the container only hosts the MCP server, which connects out to the Blender addon.
Build the image from the repo root:
docker build -t blender-mcp .
Then point your MCP client at it (the -i flag is required — the server talks to the client over stdin/stdout):
{
"mcpServers": {
"blender": {
"command": "docker",
"args": ["run", "-i", "--rm", "blender-mcp"]
}
}
}
The image defaults to BLENDER_HOST=host.docker.internal, which reaches the host's Blender out of the box with Docker Desktop on macOS and Windows.
On Linux, host.docker.internal doesn't exist and the addon only listens on localhost, so use host networking instead:
{
"mcpServers": {
"blender": {
"command": "docker",
"args": ["run", "-i", "--rm", "--network=host", "-e", "BLENDER_HOST=localhost", "blender-mcp"]
}
}
}
To enable safe mode in the container, add "-e", "BLENDER_MCP_SAFE_MODE=1" to args.
The following environment variables can be used to configure the Blender connection:
Variable Default DescriptionBLENDER_HOST
localhost
Host address for Blender socket server
BLENDER_PORT
9876
Port number for Blender socket server
BLENDER_MCP_SAFE_MODE
off
Set to 1 to validate scripts before they run in Blender (see below)
Example:
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876
By default, the AI can run any Python code in Blender. Set BLENDER_MCP_SAFE_MODE=1 to check every script before it runs and block risky code — things like reading or writing files directly, running other programs, accessing the network, or installing code that keeps running after the script ends. Normal Blender work (modeling, materials, rendering, saving, import/export) still works. Blocked scripts are sent back to the AI with the reason, so it can try again with a corrected version.
Watch the setup instruction video (assuming you have already installed uv)
Go to Claude → Settings → Developer → Edit Config → claude_desktop_config.json and include the following:
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"blender-mcp"
]
}
}
}
Use the Claude Code CLI to add the MCP for Blender server:
claude mcp add blender uvx blender-mcp
The Codex CLI, desktop app, and IDE extension all share the same config file (~/.codex/config.toml), so setting the server up once covers all three.
Register the server with the Codex CLI:
codex mcp add blender -- uvx blender-mcp
Or add it by hand to ~/.codex/config.toml (or $CODEX_HOME/config.toml):
[mcp_servers.blender]
command = "uvx"
args = ["blender-mcp"]
Or in the Codex desktop app: Settings → MCP servers → Add server → name it blender, pick STDIO, enter uvx blender-mcp as the command, then Save and restart. If the app can't find uvx, use its full path instead — see Make your client find uvx.
Check it registered with codex mcp list — the blender server should show as enabled. The tools become available the next time you start Codex.
To set environment variables (e.g. a non-default Blender host/port), pass --env KEY=VALUE flags to codex mcp add, or add them in the config file:
[mcp_servers.blender]
command = "uvx"
args = ["blender-mcp"]
env = { BLENDER_HOST = "localhost", BLENDER_PORT = "9876" }
macOS — go to Settings → MCP and paste the following:
.cursor/mcp.json in the root of the project and paste{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"blender-mcp"
]
}
}
}
Windows — go to Settings → MCP → Add Server, add a new server with the following settings:
{
"mcpServers": {
"blender": {
"command": "cmd",
"args": [
"/c",
"uvx",
"blender-mcp"
]
}
}
}
Note: Only run one instance of the MCP server (either on Cursor or Cl