Blender MCP (Model Context Protocol)

A Blender addon that enables AI assistants (like Claude) to interact with Blender through the Model Context Protocol (MCP).

Installation

1. Install the Blender Addon

Download or clone this repository
Copy the entire src/blender_mcp/addon/ directory to your Blender addons folder:
- Windows: %APPDATA%\Blender Foundation\Blender\4.x\scripts\addons\
- macOS: ~/Library/Application Support/Blender/4.x/scripts/addons/
- Linux: ~/.config/blender/4.x/scripts/addons/
Rename the copied directory from addon to blender_mcp
Open Blender and go to Edit > Preferences > Add-ons
Search for "Blender MCP" and enable the addon

2. Install the MCP Server

The MCP server runs outside Blender and communicates with it via sockets.

Install Python dependencies:
pip install mcp-server-fastmcp
Or if using the provided virtual environment:
# Activate the virtual environment source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt

3. Configure Your MCP Client

Add the Blender MCP server to your MCP client configuration (e.g., Claude Desktop):

{ "mcpServers": { "blender": { "command": "python", "args": ["-m", "blender_mcp.server"], "env": { "BLENDER_HOST": "localhost", "BLENDER_PORT": "9876" } } } }

Usage

Start Blender and enable the Blender MCP addon
Start your MCP client (Claude Desktop, etc.) with the server configured
In Blender, click the "Connect to MCP server" button in the BlenderMCP panel (N-panel > BlenderMCP)
Use Claude to interact with Blender through natural language commands

Features

Core Tools

Scene Information: Get details about objects, materials, and scene structure
Object Manipulation: Query and modify 3D objects
Viewport Screenshots: Capture Blender's 3D viewport
Code Execution: Run Python code directly in Blender

Template Engine

Template Management: Create, save, and reuse complex operations
Dynamic Overrides: Apply templates with parameter modifications
Template Search: Discover templates by tags and categories
Usage Analytics: Track template performance and success rates
Version Control: Optional Git versioning for template evolution

Asset Integrations

PolyHaven: Download HDRIs, textures, and 3D models
Sketchfab: Search and download 3D models
Hyper3D Rodin: Generate 3D models from text or images

Configuration

Blender Addon Settings

Port: Socket port for communication (default: 9876)
PolyHaven: Enable/disable PolyHaven integration
Hyper3D: Configure API keys and modes
Sketchfab: Configure API key for model downloads

Environment Variables

BLENDER_HOST: Host address (default: localhost)
BLENDER_PORT: Port number (default: 9876)

Architecture

The system consists of two main components:

Blender Addon (src/blender_mcp/addon/): Runs inside Blender, handles UI and executes Blender operations
MCP Server (src/blender_mcp/server/): Runs outside Blender, provides MCP tools and manages communication

Development

Project Structure

src/blender_mcp/ ├── addon/ # Blender addon code │ ├── handlers.py # Base command handlers │ ├── polyhaven_handlers.py # PolyHaven integration │ ├── hyper3d_handlers.py # Hyper3D integration │ ├── sketchfab_handlers.py # Sketchfab integration │ ├── ui.py # Blender UI components │ ├── server.py # Socket server for addon │ └── __main__.py # Addon registration └── server/ # MCP server code ├── connection.py # MCP server and socket client ├── tools.py # Core Blender tools ├── integrations.py # Integration tools ├── template_engine.py # Template storage and management ├── template_tools.py # MCP tools for templates ├── prompts.py # MCP prompts └── __main__.py # Server entry point templates/ # Template storage directory ├── template_name.json # Template definitions └── analytics.json # Usage statistics

Running Tests

# Test server modules python -m pytest tests/ # Or manually test imports python -c "from src.blender_mcp.server.connection import mcp; print('OK')"

Troubleshooting

Connection Issues

Ensure the Blender addon is enabled and running
Check that the port numbers match between client and server
Verify firewall settings allow socket connections

Integration Issues

Check API keys are properly configured in Blender
Ensure internet connectivity for external services
Review Blender console for error messages

Performance

Large scenes may take time to process
Asset downloads depend on internet speed
3D generation can take several minutes

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

License

See LICENSE file for details.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Related Resources

GitHub Repository

Need Help?

Report Issue

BlenderMCP