Skip to main content

Blender MCP

ADVANCED
📖8 min read

Introduction​

caution

Highly experimental. You are working with LLM's and you allow access to your scene, so approach with caution. If using Claude, data will leave your local environment. Local options are possible. Works for simple tasks and requests. Can be useful to analyze a scene and for scene management/structuring.

The Model Context Protocol (MCP) is an open standard that enables Large Language Models (LLMs) to interact with external systems and data. By integrating an MCP server within Blender, you can give LLMs direct access to your 3D scene, allowing them to query scene data, manipulate objects, adjust parameters, and automate modeling tasks through natural language instructions.

This page covers both cloud-based approaches (easiest but requires external services) and local setups (more privacy-preserving and cost-effective for heavy use).

Cloud Integration

Connect Blender to Claude or other cloud-based LLMs with minimal setup. Simple configuration but requires internet and API keys.

Local LLMs

Run LLMs locally using tools like Ollama for complete privacy and control. More setup required but no external dependencies.

Scene Automation

Automate scene operations, queries, and modifications through natural language commands executed by the AI.

What is the Model Context Protocol?​

MCP is an open standard developed to standardize how applications provide context and tools to LLMs. It defines a protocol for:

  • Tool definitions - What operations the LLM can perform
  • Resource access - What data the LLM can read and write
  • Two-way communication - Bidirectional interaction between the LLM and the application

In the context of Blender, an MCP server exposes your 3D scene (or rather, parts of Blender) as a set of tools and resources that an LLM can understand and manipulate. The LLM can then:

  • Inspect scene structure, object properties, and materials
  • Create, delete, or modify objects and materials
  • Adjust object transformations, materials, and parameters
  • Run operations based on natural language instructions
  • Provide analysis and recommendations about your scene

Cloud-Based Integration: Claude + Blender​

The easiest way to get started with Blender MCP is connecting to Claude, Anthropic's LLM service. This requires minimal setup but has important considerations.

Setup Requirements​

  1. Python environment - Blender's bundled Python or your system Python
  2. MCP server - Blender MCP server addon
  3. Claude Desktop client - Download from claude.ai

Installation Steps​

Step 1: Install Blender MCP Server

The easiest approach is using the community-maintained Blender MCP server. Install via pip:

pip install blender-mcp-server

Or clone from GitHub for the latest version:

git clone https://github.com/your-repo/blender-mcp-server
cd blender-mcp-server
pip install -e .

Step 2: Configure Claude Desktop

Edit Claude's configuration file:

  • Windows: %APPDATA%\Claude\config.json
  • Mac: ~/Library/Application Support/Claude/config.json
  • Linux: ~/.config/Claude/config.json

Add the Blender MCP server to the mcpServers section:

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-m", "blender_mcp_server"],
      "env": {
        "BLENDER_PATH": "/path/to/blender"
      }
    }
  }
}

Step 3: Connect to Your Scene

Start Blender with your scene open, then start Claude Desktop. Claude will now have access to Blender and can execute commands.

Important Considerations: Cloud-Based Integration​

⚠️ Data Privacy Warning:

When using Claude for Blender interaction, be aware that:

  • Scene data and queries are sent to Anthropic's servers
  • Your scene structure, object names, and properties are transmitted
  • This may not be suitable for sensitive investigations
  • Anthropic has privacy policies, but data leaves your control

Local LLM Integration: Ollama + Blender​

For privacy and control, you can run LLMs locally, for example by using a combination of Ollama and Cline within VSCode. This requires more technical setup, is slower (depending on your local hardware) but eliminates data transmission to other parties.

Why Local LLMs?​

Privacy:

  • All data stays on your machine
  • No external API calls or internet requirements
  • Complete control over what information the LLM accesses
  • Ideal for sensitive investigation work

Cost:

  • No per-query charges
  • One-time setup costs only
  • Can run large models if you have sufficient GPU/CPU resources

Control:

  • Choose specific model versions
  • No third-party service dependencies
  • Can customize models for your specific workflow

Setup Requirements​

  1. Ollama - Download from ollama.ai
  2. Local LLM model - e.g., Mistral, Llama 2, or Neural Chat
  3. Blender MCP server - Same as cloud setup
  4. MCP client - Local setup (can use VS Code with MCP extension)
  5. Python environment - For running MCP client

Installation Steps​

Step 1: Install and Run Ollama

  1. Download and install Ollama for your OS
  2. Open terminal and pull a model:
ollama pull mistral
# or for faster responses on limited hardware:
ollama pull neural-chat
  1. Start Ollama server (it typically runs on http://localhost:11434):
ollama serve

Step 2: Install Blender MCP Server

Same as cloud setup:

pip install blender-mcp-server

Step 3: Set Up Local MCP Client in VS Code

Install the MCP extension in VS Code:

  • Open Extensions
  • Search for "Model Context Protocol" or "MCP"
  • Install the official extension

Create a .mcp.json configuration file in your project root:

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["-m", "blender_mcp_server"],
      "env": {
        "BLENDER_PATH": "/path/to/blender"
      }
    },
    "ollama": {
      "command": "python",
      "args": ["-m", "ollama_mcp_server"],
      "env": {
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "mistral"
      }
    }
  }
}

Step 4: Connect Everything

  1. Start Ollama server (terminal window)
  2. Open Blender with your scene
  3. Open VS Code with the MCP extension
  4. The extension will discover both Blender and Ollama servers
  5. You can now interact with Blender through local Ollama

Performance Considerations​

Model selection affects speed:

  • QWEN2.5 Code (faster, 13B params) - Good for quick commands, lower VRAM
  • Mistral (balanced, 7B params) - Good balance of speed and capability
  • Llama 2 (capable, various sizes) - Larger models need more VRAM
  • Dolphin (specialized, various sizes) - Fine-tuned for code and technical tasks

Hardware recommendations:

  • GPU acceleration: 8GB+ GPU VRAM for smooth operation
  • CPU only: Works but slower; expect 5-30 second response times
  • RAM: 16GB+ system RAM recommended for larger scenes + LLM
  • Disk: Models typically require between 4-40GB

Blender MCP Server Capabilities​

Regardless of whether you use cloud or local LLMs, the Blender MCP server exposes these core capabilities:

Scene Queries​

  • List all objects in the scene
  • Get object properties (location, rotation, scale, materials)
  • Query scene statistics (object count, total vertices, etc.)
  • Inspect material and texture properties
  • Check modifier stacks and properties

Object Manipulation​

  • Create objects (mesh types, curves, empties)
  • Delete or hide/unhide objects
  • Modify transforms (location, rotation, scale)
  • Change materials and colors
  • Add/modify modifiers
  • Parent/unparent object hierarchies

Scene Organization​

  • Rename objects systematically
  • Move objects to specific collections
  • Tag objects with custom properties
  • Reorganize scene structure based on criteria
  • Generate scene reports and summaries

Automation Examples​

Rename all measurement objects:

"Rename all objects starting with 'measure_' to 'MEASUREMENT_' followed by their index"

Organize by type:

"Create collections for camera, lights, and geometry. Move all objects to their respective collections based on object type"

Geometric analysis:

"Find all objects below height 0 and report their locations and bounding box sizes"

Scene documentation:

"Generate a structured report of the scene including object count, material count."

Summary​

Integrating MCP with Blender connects your 3D scene to the reasoning and automation capabilities of Large Language Models. For visual investigators, this enables rapid iteration, scene documentation, and complex automation through natural language.

Cloud-based integration (Claude) offers the easiest setup and most capable LLM, but sends scene data externally, suitable for non-sensitive work and prototyping.

Local integration (Ollama + VS Code) requires more setup but keeps all data private and eliminating API costs, better for sensitive investigations and heavy usage scenarios.

Key Takeaways:

  • MCP provides standardized protocol for LLM-application integration
  • Cloud approach is simpler but exposes scene data externally
  • Local approach preserves privacy but requires more technical setup
  • Both approaches expose similar Blender capabilities (queries, manipulation, automation)
  • Choose based on your privacy requirements, budget, and technical comfort level
  • Start with simple queries to learn the system before attempting complex automation
  • Verify AI-executed changes before saving important work

Documentation for Methodology​

To ensure your work aligns with the Berkeley Protocol and the Guide for Judges, use the following points to document your use of Blender MCP.

Methodology: How to document Blender MCP

In Your Method Section​

Guidance: Describe the purpose, the tool version, and the input data.

  • Investigative Objective: To automate [Task Name] (e.g., scene organization, data querying) using an LLM interface.
  • Software Version: Blender MCP [Version] with [LLM Provider] (Model: [Model Name]).
  • Input Data: Natural language instructions provided to the model.

In Your Decision Log​

Guidance: Record the specific procedural parameters and integrity checks.

  • Specific Settings: Model ([Name/Version]), Temperature ([Value]), System Prompt ([Description]).
  • Assumptions: Acknowledged that the LLM may misinterpret instructions or hallucinate code.
  • Integrity Check: Manually reviewed all AI-executed changes (object names, locations, properties) before saving.
  • Date Performed: [YYYY-MM-DD].

Verification & Mitigation​

Guidance: How did you mitigate bias or verify accuracy?

  • Verification: Validated the results against a manual control or by inspecting the generated Python code/API calls.
  • Bias Mitigation: Used specific, unambiguous prompts and verified results for important tasks.

Common Limitations​

  • LLMs can generate incorrect or destructive code; "undo" may not always be reliable.
  • Complex geometric operations are often beyond the capability of current text-based models.

Example Methodology Statement​

"Scene organization was automated using Blender MCP with the Claude 3.5 Sonnet model. The instruction 'Rename all objects in collection X to format Y' was executed. All resulting name changes were manually verified against the project naming convention. No geometric modifications were performed by the AI."

Further Resources:

Tags:
Last updated on by blender-visual-investigation