MCP Client (Claude/Cursor/CLI)
         │ HTTP / stdio
         ▼
┌─────────────────────┐
│   FastMCP Server    │  ← server.py  (port 8000)
│   blender-open-mcp  │
└─────────────────────┘
    │ TCP socket           │ HTTP
    ▼                      ▼
┌──────────────┐    ┌─────────────┐
│  Blender     │    │   Ollama    │  (port 11434)
│  Add-on      │    │  llama3.2   │
│  addon.py    │    │  gemma3...  │
│  (port 9876) │    └─────────────┘
└──────────────┘
       │ bpy
       ▼
  Blender Python API

git clone https://github.com/dhakalnirajan/blender-open-mcp.git
cd blender-open-mcp

# Create virtual environment and install
uv venv
source .venv/bin/activate   # Linux / macOS
# .venv\Scripts\activate    # Windows

uv pip install -e .

ollama pull ollama run llama3.2

blender-mcp

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

blender-mcp --transport stdio

# 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

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())

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

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

# Run tests
pytest tests/ -v

# Type checking
mypy src/

# Linting
ruff check src/ client/