2. Install the Blender Add-on

1. Open Blender
2. Go to Edit → Preferences → Add-ons → Install...
3. Select addon.py from the repository root
4. Enable "Blender MCP"
5. Open the 3D Viewport, press N, find the Blender MCP panel
6. Click "Start MCP Server" (default port: 9876)

3. Pull an Ollama model

ollama pull ollama run llama3.2

(Other models like Gemma3 can also be used.)

Setup

1. Start the Ollama Server: Ensure Ollama is running in the background.

2. Start the MCP Server:

blender-mcp

Custom options:

blender-mcp \
  --host 127.0.0.1 \
  --port 8000 \
  --blender-host localhost \
  --blender-port 9876 \
  --ollama-url http://localhost:11434 \
  --ollama-model llama3.2

For stdio transport (Claude Desktop, Cursor):

blender-mcp --transport stdio

Usage

MCP Client CLI

# Interactive shell
blender-mcp-client interactive

# One-shot scene info
blender-mcp-client scene

# Call a specific tool
blender-mcp-client tool blender_get_scene_info
blender-mcp-client tool blender_create_object '{"primitive_type": "SPHERE", "name": "MySphere"}'

# Natural language prompt
blender-mcp-client prompt "Create a metallic sphere at position 0, 0, 2"

# List all available tools
blender-mcp-client tools

Python API

import asyncio
from client.client import BlenderMCPClient

async def demo():
    async with BlenderMCPClient("http://localhost:8000") as client:
        # Scene inspection
        print(await client.get_scene_info())

        # Create objects
        await client.create_object("CUBE", name="MyCube", location=(0, 0, 0))
        await client.create_object("SPHERE", name="MySphere", location=(3, 0, 0))

        # Apply materials
        await client.set_material("MyCube", "GoldMat", color=[1.0, 0.84, 0.0, 1.0])

        # Move objects
        await client.modify_object("MySphere", location=(3, 0, 2), scale=(1.5, 1.5, 1.5))

        # PolyHaven assets
        categories = await client.get_polyhaven_categories("textures")
        await client.download_polyhaven_asset("brick_wall_001", resolution="2k")
        await client.set_texture("MyCube", "brick_wall_001")

        # Render
        await client.render_image("/tmp/my_render.png")

        # AI assistance
        response = await client.ai_prompt(
            "Write bpy code to add a sun light pointing down"
        )
        print(response)

        # Execute the generated code
        await client.execute_code(response)

asyncio.run(demo())

Claude Desktop / Cursor Integration

Add to your mcp.json (or ~/.cursor/mcp.json):

{
  "mcpServers": {
    "blender-open-mcp": {
      "command": "blender-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Available Tools

| Tool | Description | Modifies Blender | |------|-------------|-----------------| | blender_get_scene_info | Full scene summary: objects, camera, render settings | No | | blender_get_object_info | Detailed object info: transforms, materials, mesh stats | No | | blender_create_object | Add a primitive mesh (CUBE, SPHERE, CYLINDER, ...) | Yes | | blender_modify_object | Change location, rotation, scale, visibility | Yes | | blender_delete_object | Remove an object from the scene | Yes ⚠️ | | blender_set_material | Create and assign a Principled BSDF material | Yes | | blender_render_image | Render current scene to a file | Yes | | blender_execute_code | Run arbitrary Python/bpy code in Blender | Yes ⚠️ | | blender_get_polyhaven_categories | List PolyHaven asset categories | No | | blender_search_polyhaven_assets | Search PolyHaven library with pagination | No | | blender_download_polyhaven_asset | Download & import a PolyHaven asset | Yes | | blender_set_texture | Apply a downloaded PolyHaven texture to an object | Yes | | blender_ai_prompt | Send a natural language prompt to Ollama | No | | blender_get_ollama_models | List available local Ollama models | No | | blender_set_ollama_model | Switch the active Ollama model | No | | blender_set_ollama_url | Update the Ollama server URL | No |

Default Ports

| Service | Port | |---------|------| | FastMCP Server | 8000 | | Blender Add-on (TCP) | 9876 | | Ollama | 11434 |

Development

# Install dev dependencies
uv pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Type checking
mypy src/

# Linting
ruff check src/ client/

Troubleshooting

| Problem | Solution | |---------|----------| | Cannot connect to Blender add-on | Open Blender → N-sidebar → Blender MCP → Start MCP Server | | Cannot connect to Ollama | Run ollama serve in a terminal | | Object not found | Check exact object name via blender_get_scene_info | | Render fails | Ensure the output directory exists and is writable | | PolyHaven download fails | Check internet connection; try a lower resolution |

License

MIT License. See LICENSE for details.

This project is not affiliated with the Blender Foundation.