mcp-for-blender
Applicationahujasid/mcp-for-blender
MCP server and Blender addon letting any LLM control Blender 3D.
Overview
A community-built integration that connects Blender to LLMs via the Model Context Protocol. It combines a Blender addon socket server with a Python MCP server, enabling prompt-assisted 3D modeling, scene creation, object and material manipulation, and code execution. It also supports importing assets from Poly Haven, Sketchfab, and AI 3D model generators.
README Preview
\n\n# MCP for Blender\n\n**Connect Blender to any LLM**\n\n*formerly `blender-mcp` — the PyPI package is now [`mcp-for-blender`](https://pypi.org/project/mcp-for-blender/).*\n*Existing setups keep working; no config change is required. [Read more](https://github.com/ahujasid/mcp-for-blender/issues/366)*\n\n**Disclaimer:** This is a third-party integration and not made by Blender\n\nPrompt-assisted 3D modeling, scene creation, and manipulation — driven by AI.\n\n[](https://pepy.tech/projects/blender-mcp)\n[](https://pypi.org/project/mcp-for-blender/)\n[](LICENSE)\n[](https://discord.gg/SNqPn4TcKQ)\n\n[**Website**](https://mcp-for-blender.com/) · [**Full Tutorial**](https://www.youtube.com/watch?v=lCyQ717DuzQ) · [**Discord**](https://discord.gg/SNqPn4TcKQ) · [**Sponsor**](https://github.com/sponsors/ahujasid) · [**Buy me a coffee**](https://buymeacoffee.com/ahujasid) · [**Feedback**](https://cal.com/siddharth-ahuja/feedback-call)\n\n\n\n\n\n**Supporters**\n\n[CodeRabbit](https://www.coderabbit.ai/)\n[Kevin Guanche Darias](https://github.com/KevinGuancheDarias)\n[Guillermo Rauch](https://github.com/rauchg)\n\n**All supporters:** [Support this project](https://github.com/sponsors/ahujasid)\n\n\n\n---\n\n## Quickstart\n\n> **Note:** the PyPI package `blender-mcp` is now **`mcp-for-blender`**. Existing setups\n> keep working — `uvx blender-mcp` still runs the server and **no config change is\n> required**. New installs should use `mcp-for-blender`.\n> [What changed and why](https://github.com/ahujasid/mcp-for-blender/issues/366)\n\n**One command** sets up your AI apps and the Blender addon:\n\n**macOS / Linux**\n\n```bash\ncurl -LsSf https://www.mcp-for-blender.com/install.sh | sh\n```\n\n**Windows** (PowerShell)\n\n```powershell\npowershell -ExecutionPolicy ByPass -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"\n```\n\nAlready have uv? Run `uvx mcp-for-blender setup` instead.\n\nIt installs [uv](https://docs.astral.sh/uv/) if needed, finds the MCP clients on y
FAQ (3)
TroubleshootingHow to fix UnicodeDecodeError crash when running 'uvx mcp-for-blender setup' on German/non-English Windows?
The crash happens in blender_is_running() because tasklist output uses the OEM code page (cp850) while Python decodes with cp1252, failing on characters like 'ü'.
**Fix (for maintainers/source installs):** In blender_mcp/setup_cli.py line ~607, pass encoding="oem" (or errors="replace") to the subprocess.run call that runs tasklist /FI "IMAGENAME eq blender.exe" /NH.
**Workarounds for users:**
1. Run chcp 65001 and set $env:PYTHONUTF8=1 (PowerShell) before running uvx mcp-for-blender setup.
2. Or skip the failing step: the addon file is already copied before the crash, so just open Blender and enable the addon manually under Edit > Preferences > Add-ons.
TroubleshootingWhy does blender-mcp hang after 'Successfully connected to Blender on startup' with no response?
It's not hanging — this is normal behavior. uvx blender-mcp is a stdio-based MCP server, not an interactive CLI. After connecting to Blender, it silently waits for MCP protocol messages on stdin/stdout from an MCP client (Claude Desktop, Cursor, etc.). Running it directly in a terminal only verifies the connection; it will show no further output, and the Ctrl+C traceback (asyncio CancelledError) is just normal shutdown noise, not an error.
To actually use it:
1. In Blender: Edit > Preferences > Add-ons > install the addon.py file, enable 'Interface: Blender MCP'. In the 3D viewport press N, open the BlenderMCP tab, and click 'Connect to Claude' (starts the socket server on port 9876).
2. Configure your MCP client instead of running the server manually. For Claude Desktop, edit claude_desktop_config.json:
{"mcpServers": {"blender": {"command": "uvx", "args": ["blender-mcp"]}}}
For Cursor: Settings > MCP > Add new server, command: uvx blender-mcp.
3. Restart the client and send prompts there (e.g., 'create a cube in Blender') — Blender will now respond.
Only run uvx blender-mcp standalone as a connectivity test, then close it with Ctrl+C.
TroubleshootingHow to fix pywin32 'os error 32: file being used by another process' when running blender-mcp via uvx on Windows?
The error occurs because uvx blender-mcp creates an ephemeral environment each run, and the locked pywin32 files in uv's cache can't be replaced. Fix by installing blender-mcp as a persistent uv tool instead:
1. Install it into uv's tool store: uv tool install blender-mcp
2. Force-update it: uv tool upgrade blender-mcp
3. Verify the installation: uv tool list
Your MCP config can stay the same ("command": "uvx", "args": ["blender-mcp"]), since uvx will now resolve the already-installed tool instead of rebuilding a temporary environment and hitting the file lock. Manually deleting the locked cache directory (e.g. C:\Users\<you>\AppData\Local\uv\cache\builds-v0\...) alone does not fix it, because the lock recurs on the next ephemeral install.