Control Blender with AI. A Blender 4.0+ addon that runs a Model Context Protocol (MCP) server, enabling AI assistants like Claude to create, modify, and export 3D assets programmatically.
Blender MCP bridges the gap between AI language models and professional 3D content creation. By implementing the Model Context Protocol, it allows AI assistants to understand Blender scenes, generate procedural geometry, validate assets for game engines, and automate complex 3D workflows—all through natural language.
Perfect for:
- Game developers needing Unity-ready assets with automated validation
- 3D artists seeking AI-assisted procedural generation and automation
- Technical artists building AI-powered asset pipelines
- Developers integrating AI into 3D content workflows
Scene Introspection
- Query scene hierarchies, object properties, and data blocks
- Inspect meshes, materials, armatures, and animations
- Analyze modifiers, constraints, and node graphs
- Export scene information in structured formats
Object Manipulation
- Create, modify, and delete objects programmatically
- Manage transforms, parenting, and collections
- Apply and configure modifiers and constraints
- Duplicate and instance objects with full control
Mesh Editing with BMesh
- Create meshes from vertex and face data
- Edit geometry (extrude, bevel, subdivide, merge)
- Set vertex colors, UVs, and weights
- Boolean operations (union, difference, intersect)
Visual Capture
- Viewport screenshots from single or multiple angles
- Annotated renders with highlights and labels
- Before/after comparisons and difference visualization
- Node editor and timeline captures
- Animation recording with frame sequences
Unity Integration
- Pipeline profiles for Standard, URP, and HDRP
- Mesh validation (vertex limits, UVs, normals, n-gons)
- Humanoid rig validation with bone mapping
- Material compatibility checking and conversion
- FBX export with pipeline-specific settings
Procedural Generation
12 Mesh Types:
- Terrain (noise-based, heightmap)
- Architecture (walls, floors, stairs, columns, arches)
- Organic shapes (rocks, tree trunks)
- Parametric primitives (gears, springs, torus knots)
9 Material Templates:
- Natural materials (wood grain, marble)
- Surface effects (fabric, edge wear, scratches, dirt)
- Patterns (bricks, tiles, hexagons)
10 Geometry Node Templates:
- Distribution (scatter, linear/radial/grid arrays)
- Curve utilities (pipes, rails, cables)
- Deformers (bend, twist, taper)
8 Animation Patterns:
- Procedural motion (idle breathing, bounce, oscillation, pendulum)
- Drivers (sine, noise, spring, expression-based)
Script Generation
- Generate standalone Python scripts from templates
- Create custom Blender addons with proper registration
- Build custom operators and UI panels
- Export scripts with dependencies and documentation
- Download
blender_mcp.zipfrom Releases - In Blender: Edit > Preferences > Add-ons
- Click Install... and select the downloaded zip file
- Enable "Blender MCP" in the addon list
- The MCP panel appears in the 3D Viewport sidebar (press N > MCP tab)
Option A: Manual Start
- Open Blender
- Press N to open the sidebar, go to the MCP tab
- Click Start Server
Option B: Auto-Start
- Go to Edit > Preferences > Add-ons > Blender MCP
- Enable Auto-Start Server
- Server starts automatically when Blender launches
The server runs on http://localhost:9876 by default (Streamable HTTP transport).
Quick setup - Run one of these commands in your terminal:
# User-level (available across all projects)
claude mcp add --transport http --scope user blender http://127.0.0.1:9876
# Project-level (current project only, default)
claude mcp add --transport http blender http://127.0.0.1:9876Scope options:
| Scope | Description | Config Location |
|---|---|---|
--scope user |
Available across all your projects | ~/.claude.json |
--scope local |
Current project only, private (default) | .mcp.json |
--scope project |
Current project, shared with team | .mcp.json |
Or manually - Add to your settings file:
{
"mcpServers": {
"blender": {
"type": "http",
"url": "http://127.0.0.1:9876"
}
}
}For user-level: ~/.claude.json | For project-level: .mcp.json in project root
Ask Claude to control Blender through natural language:
Scene Analysis
"Show me what's in the current scene"
"List all mesh objects with their vertex counts"
"What modifiers are applied to the Cube?"
Object Creation
"Create a UV sphere at position (0, 0, 2) with radius 1.5"
"Add a subdivision surface modifier to the sphere with 2 levels"
"Duplicate the sphere 5 times in a grid pattern"
Procedural Generation
"Generate a procedural terrain mesh with noise displacement"
"Create a brick wall material with realistic wear"
"Generate a torus knot with 3 coils and 7 twists"
Visual Capture
"Take a screenshot of the viewport from the front, side, and top"
"Render a quick preview of the current frame"
"Create a before/after comparison showing the modifier effects"
Unity Integration
"Set the Unity export profile to URP"
"Validate this character mesh for Unity humanoid rig"
"Check if these materials are compatible with HDRP"
Automation
"Select all objects with subdivision modifiers and reduce their levels to 1"
"Export all meshes in the 'Props' collection as FBX for Unity"
"Generate a Python script that creates a procedural city block"
Access via Edit > Preferences > Add-ons > Blender MCP:
| Setting | Description | Default |
|---|---|---|
| Server Port | TCP port for MCP connections | 9876 |
| Auto-Start Server | Start server when Blender launches | Disabled |
| Unity Target | Default Unity render pipeline | URP |
| Script Output Directory | Location for generated scripts | //scripts/ |
| Log Level | Logging verbosity (Debug/Info/Warning/Error) | Info |
| Extension Paths | Additional paths for custom MCP extensions | Empty |
The MCP sidebar panel (View3D > Sidebar > MCP) displays:
- Server status (Running/Stopped)
- Server address and port
- Connected client count
- Registered tool count
- Quick start/stop/restart controls
Blender MCP provides 86 tools organized into categories:
| Tool | Description |
|---|---|
scene_get_overview |
Scene settings, frame range, render config |
scene_get_hierarchy |
Full object/collection tree with visibility states |
blend_get_data_blocks |
List data blocks by type (meshes, materials, etc.) |
blend_get_libraries |
Linked/appended library information |
object_get_info |
Object transform, dimensions, and properties |
object_get_modifiers |
Complete modifier stack with parameters |
object_get_constraints |
Constraint settings and targets |
mesh_get_info |
Vertex/edge/face counts, topology analysis |
material_get_info |
Material properties and node setup |
armature_get_info |
Bone hierarchy and deform settings |
| Tool | Description |
|---|---|
object_create |
Create primitives, empties, cameras, lights |
object_modify |
Set transform, parent, visibility, collections |
object_delete |
Remove objects with hierarchy options |
object_duplicate |
Copy objects (linked or full duplication) |
modifier_add |
Add modifiers (subdivision, array, etc.) |
modifier_remove |
Remove specific modifiers |
modifier_set |
Modify modifier parameters |
constraint_add |
Add constraints (copy location, track to, etc.) |
constraint_remove |
Remove constraints |
constraint_set |
Configure constraint parameters |
| Tool | Description |
|---|---|
mesh_create_from_data |
Create mesh from vertices, edges, faces |
mesh_edit |
Extrude, bevel, subdivide, merge operations |
mesh_transform |
Transform selected geometry |
mesh_set_attribute |
Set vertex colors, UVs, vertex groups |
mesh_boolean_combine |
Boolean operations (union, difference, intersect) |
| Tool | Description |
|---|---|
viewport_screenshot |
Single viewport capture with transparency |
viewport_screenshot_angles |
Multi-angle captures (front, side, top, etc.) |
viewport_annotated |
Screenshots with annotations and highlights |
viewport_compare |
Before/after split-screen comparisons |
viewport_diff |
Visual difference highlighting |
render_preview |
Quick render with reduced quality |
render_region |
Render specific frame range |
nodes_screenshot |
Capture node editor graphs |
animation_record |
Record animation as image sequence |
| Tool | Description |
|---|---|
material_create |
Create new materials with node setup |
material_set_property |
Set material properties (color, roughness, etc.) |
material_assign |
Assign material to objects or faces |
material_node_add |
Add shader nodes |
material_node_connect |
Connect node sockets |
procedural_material |
Generate procedural materials (wood, marble, etc.) |
| Tool | Description |
|---|---|
procedural_mesh |
Generate terrain, architecture, organic shapes |
mesh_from_description |
Natural language to geometry conversion |
geometry_nodes_template |
Create geometry node setups (scatter, arrays, etc.) |
animation_pattern |
Generate procedural animations |
| Tool | Description |
|---|---|
unity_set_profile |
Set target pipeline (Standard/URP/HDRP) |
unity_get_profile |
Get current profile settings |
unity_validate_mesh |
Check vertex limits, UVs, scale, normals |
unity_validate_rig |
Validate humanoid bone mapping |
unity_validate_materials |
Check material compatibility |
unity_export_fbx |
Export with pipeline-specific FBX settings |
| Tool | Description |
|---|---|
execute_python |
Run arbitrary Python code in Blender context |
script_generate |
Generate standalone scripts from templates |
addon_generate |
Create custom Blender addons with UI |
operator_generate |
Build custom operators with registration |
For complete tool documentation with parameters and examples, see docs/tools.md.
Blender MCP includes specialized tools for Unity game development workflows.
Pipeline Profiles: Configure Blender for Standard, URP, or HDRP pipelines with automatic:
- Material settings (PBR workflow, texture channels)
- Mesh optimization (vertex limits, LOD preparation)
- FBX export settings (axis conversion, scale, bake options)
Validation Tools: Ensure assets meet Unity requirements:
- Mesh validation: Vertex count limits, UV channels, normal consistency, n-gon detection
- Rig validation: Humanoid bone mapping, hierarchy checks, bind pose verification
- Material validation: Shader compatibility, texture resolution, channel usage
Export Automation: One-click FBX export with profile-specific settings for optimal Unity import.
See docs/unity-integration.md for detailed examples and best practices.
The addon follows a modular architecture:
blender_mcp/
├── server/ # MCP TCP server implementation
├── registry.py # Tool registration decorator system
├── base.py # Base types, errors, utilities
├── tools/ # Tool implementations by category
│ ├── introspection.py
│ ├── manipulation.py
│ ├── mesh.py
│ ├── visual.py
│ ├── materials.py
│ ├── procedural.py
│ ├── unity.py
│ └── scripting.py
├── generators/ # Procedural generation algorithms
│ ├── mesh_gen.py
│ ├── material_gen.py
│ ├── geonodes_gen.py
│ └── animation_gen.py
├── unity/ # Unity pipeline profiles and validation
└── extensions/ # Extension system for custom tools
Tool Registration: Tools are registered using the @register_tool decorator:
from blender_mcp.registry import register_tool, ToolResult
@register_tool(
name="my_custom_tool",
description="Does something useful in Blender",
parameters={
"object_name": {
"type": "string",
"description": "Name of the object to modify"
}
},
category="manipulation",
)
def my_custom_tool(object_name: str) -> ToolResult:
"""Implementation of custom tool."""
import bpy
obj = bpy.data.objects.get(object_name)
if obj is None:
return ToolResult.error(f"Object '{object_name}' not found")
# Perform operations...
return ToolResult.success(data={"modified": object_name})Ask Claude to create complex geometry through iterative refinement:
- "Create a low-poly spaceship hull with 8 panels"
- "Add greebles and details to the surface"
- "Generate a cockpit window with beveled edges"
Build production pipelines with AI coordination:
- Batch process multiple objects with consistent modifiers
- Validate entire asset libraries for game engine compatibility
- Generate LOD chains with decreasing polygon counts
- Export organized FBX batches with naming conventions
Leverage procedural tools with AI direction:
- "Generate a medieval city block with varied building heights"
- "Create a forest floor with scattered rocks and tree stumps"
- "Build a sci-fi corridor with modular wall panels"
Explore Blender's capabilities with AI guidance:
- "Show me how to use geometry nodes for instancing"
- "Create a material that looks like weathered copper"
- "Demonstrate the difference between subdivision methods"
Port already in use
- Check if another application is using port 9876
- Change the port in Edit > Preferences > Add-ons > Blender MCP
- Try ports like 9877, 9878, etc.
Python errors
- Open Blender's system console (Window > Toggle System Console on Windows)
- Check for error messages indicating missing dependencies
- Ensure you're running Blender 4.0 or later
Connection refused
- Verify the server is running (check sidebar panel status)
- Ensure firewall allows local connections on the configured port
- Confirm client is configured for the correct host and port
- Try restarting both Blender and the MCP client
Connection timeout
- Check antivirus isn't blocking connections
- Verify no VPN interfering with localhost connections
- Try explicitly using
127.0.0.1instead oflocalhost
Mode-related errors
- Many tools require Object mode; exit Edit mode before running
- Check Blender's Info editor for operator errors
- Ensure objects are not locked or hidden
Object not found
- Object names are case-sensitive: "Cube" ≠ "cube"
- Check for trailing spaces in object names
- Use
scene_get_hierarchyto verify exact object names
Modifier/constraint errors
- Some modifiers require specific object types (e.g., Subdivision requires mesh)
- Constraints need valid targets
- Check modifier order—some modifiers conflict
Performance issues
- Large scenes may slow down introspection tools
- Reduce viewport complexity when using screenshot tools
- Disable auto-save during intensive operations
Contributions are welcome! We appreciate:
- Bug reports and feature requests via GitHub Issues
- Pull requests for bug fixes, new tools, or documentation improvements
- Extensions and plugins shared with the community
To contribute:
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-tool) - Make your changes with clear commit messages
- Test thoroughly in Blender 4.0+
- Submit a pull request with description of changes
Development setup:
- Use the development installation method (symlink)
- Enable "Debug" log level in addon preferences
- Check Blender's system console for detailed logs
- Follow existing code style and structure
Creating custom tools:
- Place tools in appropriate category file under
tools/ - Use the
@register_tooldecorator for automatic registration - Follow parameter schema format for type validation
- Return
ToolResult.success()orToolResult.error() - Document parameters and return values clearly
Creating extensions:
- See
extensions/example/for template structure - Place extensions in configured extension paths
- Use reload button in preferences to test changes
Software:
- Blender 4.0 or later (4.2+ recommended)
- Python 3.10+ (included with Blender)
- MCP-compatible client (Claude Code, etc.)
Operating Systems:
- Windows 10/11
- macOS 10.15+
- Linux (Ubuntu 20.04+, Fedora 36+, etc.)
Optional:
- Unity 2021.3+ (for Unity integration features)
- Git (for development installation)
MIT License - see LICENSE file for details.
Copyright (c) 2026 Blender MCP Contributors
- Anthropic for the Model Context Protocol specification
- Blender Foundation for the Blender Python API
- The open-source community for inspiration and feedback
- GitHub: https://github.com/Bluepuff71/blender-mcp
- Documentation: docs/tools.md
- Unity Integration: docs/unity-integration.md
- MCP Specification: https://modelcontextprotocol.io/
- Blender Python API: https://docs.blender.org/api/current/
Ready to blend AI with 3D? Install Blender MCP and start creating with Claude today.