Blender MCP
# Blender MCP
[](https://github.com/axcel-blade/Blender-MCP/actions/workflows/ci.yml)
[](https://github.com/axcel-blade/Blender-MCP/actions/workflows/cd.yml)
[](https://github.com/axcel-blade/Blender-MCP/releases/latest)
[](LICENSE)
[](https://www.python.org/)
[](https://docs.astral.sh/uv/)
[](https://www.blender.org/)
[](docs/ARCHITECTURE.md)
[](SECURITY.md)
Production-oriented **Model Context Protocol (MCP)** integration for Blender. AI clients (Claude Desktop, Cursor, VS Code, Codex, Windsurf, and others) can inspect scenes, model, shade, light, render, and visually verify work through a local bridge.
This project is **not** affiliated with the Blender Foundation.
## Features
- MCP stdio server + Blender addon TCP bridge (localhost by default)
- Scene inspection, object/mesh modeling, materials, modifiers, cameras, lights
- Geometry Nodes helpers with socket inspection
- Viewport screenshots and render previews for visual verification
- Animation keyframes, import/export, project save/load
- Optional asset providers (Poly Haven, Sketchfab, Poly Pizza, AI 3D stubs)
- Script execution with explicit permission modes (restricted / confirmation / trusted)
- Auth token, path allow-lists, render limits, tool-group toggles
## Prerequisites
- [uv](https://docs.astral.sh/uv/) (required)
- Blender 3.6+ (4.x recommended)
## Quick start
Install site (Astro / GitHub Pages): [axcel-blade.github.io/Blender-MCP](https://axcel-blade.github.io/Blender-MCP/)
**Windows (PowerShell)** — one liner:
```powershell
irm https://axcel-blade.github.io/Blender-MCP/install.ps1 | iex
```
**macOS / Linux:**
```bash
curl -LsSf https://axcel-blade.github.io/Blender-MCP/install.sh | sh
```
Or from a local clone with uv:
```powershell
uv sync
uv run blender-mcp install-addon
```
1. Blender → **Edit → Preferences → Add-ons** → enable **Blender MCP**
2. 3D Viewport → press **N** → **AI / MCP** → **Start**
3. Point your MCP client at:
```json
{
"mcpServers": {
"blender": {
"command": "uv",
"args": ["run", "--directory", "C:/path/to/Blender-MCP", "blender-mcp"]
}
}
}
```
## Documentation
| Document | Purpose |
|----------|---------|
| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design |
| [docs/INSTALLATION.md](docs/INSTALLATION.md) | Install & MCP client setup |
| [docs/CONFIGURATION.md](docs/CONFIGURATION.md) | Config & environment |
| [docs/TOOLS.md](docs/TOOLS.md) | MCP tools overview |
| [docs/SECURITY.md](docs/SECURITY.md) | Technical security controls |
| [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) | Common failures |
| [CHANGELOG.md](CHANGELOG.md) | Version history |
| [CONTRIBUTING.md](CONTRIBUTING.md) | Git Flow & contribution guide |
| [SUPPORT.md](SUPPORT.md) | How to get help |
| [SECURITY.md](SECURITY.md) | Vulnerability reporting |
| [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | Community standards |
| [LICENSE](LICENSE) | MIT license |
## Architecture
```
AI Client --stdio MCP--> blender-mcp server --TCP NDJSON--> Blender addon --bpy--> Blender
```
See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
## Git Flow
| Branch | Purpose |
|--------|---------|
| `main` | Production releases |
| `develop` | Integration |
| `feature/*` | Features → `develop` |
| `release/*` | Release prep → `main` + `develop` |
| `hotfix/*` | Urgent fixes from `main` |
Details: [CONTRIBUTING.md](CONTRIBUTING.md).
## Security
- Bridge binds to `127.0.0.1` unless remote mode is explicitly enabled
- Optional shared auth token
- `execute_blender_code` is **not a sandbox** — keep `script_permission=restricted` unless you trust the client
- Path allow-lists for file operations when configured
Report vulnerabilities privately via [SECURITY.md](SECURITY.md).
## Development
This project is managed exclusively with **uv** (lockfile + virtualenv).
```powershell
uv sync
uv run pytest
uv run ruff check src tests
uv run pyright
```
Diagnose a live Blender connection:
```powershell
uv run blender-mcp diagnose
```
## License
MIT © AXCEL BLADE — see [LICENSE](LICENSE).
External asset providers retain their own licenses and attribution requirements.
TDQS
Scored across 156 tools
Many tools overlap heavily: get_materials vs list_materials, get_modifiers vs list_modifiers, get_scene_info vs get_scene_summary, and create_primitive vs dozens of primitive-specific creators. Render/capture tools also blur together (render_scene, render_preview, render_final; capture_viewport, get_viewport_screenshot, capture_scene_preview). An agent can still pick a reasonable tool in many cases, but several boundaries are genuinely unclear.
The surface is overwhelmingly snake_case, but verb conventions are inconsistent: get_ and list_ are used interchangeably for the same resource (materials/modifiers), some tools are noun-only (camera_view, mesh_cleanup, organize_scene), and capture_ vs render_ vs get_ overlap conceptually. It remains readable, but the naming does not reliably encode resource+action.
156 tools is far beyond a well-scoped surface, even for a broad Blender domain. The set contains many convenience wrappers and near-duplicates (create_sphere, create_uv_sphere, create_primitive, create_cube, etc.) that inflate the count without adding distinct capability.
Coverage is extremely broad: scene/object inspection, mesh editing, materials and nodes, cameras, lights, rendering, animation, assets, file operations, collections, viewport capture, and Python execution. Almost every core Blender workflow appears represented, with no obvious lifecycle dead ends.