Blender MCP Server — How It Works & Technical Deep Dive

Yes, Blender has an MCP server. The Blender MCP project  provides a fully functional Model Context Protocol server that connects AI clients like Claude, Cursor, and VSCode to Blender 3D. This page explains how it works under the hood — the architecture, the socket protocol, every available tool, and how to configure it for your workflow.

What Is an MCP Server?

The Model Context Protocol (MCP) is an open standard created by Anthropic that lets AI models interact with external tools and data sources. An MCP server exposes a set of “tools” (functions) that an AI client can discover and call. Think of it as a standardized plugin interface for AI.

When Claude (or Cursor, VSCode, etc.) connects to an MCP server, it:

1. Discovers what tools are available (e.g., create_object, set_material)
2. Decides which tools to call based on your natural language prompt
3. Sends structured commands to the server
4. Receives results and uses them to continue the conversation

Blender MCP is one of many MCP servers — others exist for databases, file systems, web scraping, and more. What makes Blender MCP unique is that it bridges the AI ↔ Blender gap through a socket-based architecture.

Blender MCP Architecture

The system has two components that communicate via TCP sockets:

┌─────────────────┐     MCP Protocol      ┌─────────────────┐     TCP Socket      ┌─────────────────┐
│                 │    (stdio/SSE)         │                 │    (JSON over TCP)  │                 │
│   AI Client     │◄────────────────────►│   MCP Server    │◄──────────────────►│   Blender       │
│  (Claude,       │                       │  (server.py)    │                     │  (addon.py)     │
│   Cursor,       │  Tool discovery       │                 │  Commands &         │                 │
│   VSCode)       │  Tool execution       │  Translates     │  Responses          │  Socket server  │
│                 │  Result streaming      │  MCP ↔ Socket   │                     │  Python exec    │
└─────────────────┘                       └─────────────────┘                     └─────────────────┘

Data flow for a typical request:

1. User sends a prompt in Claude: “Create a red cube”
2. Claude analyzes the prompt and decides to call the create_object MCP tool
3. The MCP server (server.py) receives the tool call via stdio
4. It serializes the command as JSON and sends it to Blender’s socket server
5. The Blender addon (addon.py) receives the JSON, executes the Python code in Blender
6. The result (success/failure, object data) is sent back through the socket
7. The MCP server returns the result to Claude
8. Claude reports back to the user

The Socket Server (addon.py)

The Blender addon (addon.py) is a standard Blender add-on that registers as “Interface: Blender MCP”. When activated, it:

• Opens a TCP socket server on localhost:9876 (configurable)
• Listens for incoming JSON commands from the MCP server
• Executes commands within Blender’s Python environment
• Returns JSON responses with results

Communication Protocol

Commands and responses use a simple JSON-based protocol over TCP:

Command format:

{
  "type": "command_name",
  "params": {
    "key": "value"
  }
}

Response format:

{
  "status": "success",
  "result": { ... }
}

Environment Variables

You can configure the socket connection using environment variables:

This is useful for running Blender on a remote machine:

export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876

The MCP Protocol Server (server.py)

The MCP server (src/blender_mcp/server.py) is a Python application distributed as the blender-mcp package on PyPI. It:

• Implements the MCP protocol (stdio transport)
• Registers all available tools that AI clients can discover
• Translates MCP tool calls into Blender socket commands
• Handles connection lifecycle with the Blender addon
• Runs via uvx blender-mcp (the AI client manages this automatically)

You never need to start this server manually — Claude Desktop, Cursor, and other MCP-compatible clients launch it automatically based on your config file.

Available MCP Tools & Commands

The Blender MCP server exposes these tools to AI clients:

Scene & Object Tools

Material & Visual Tools

Asset Integration Tools

Advanced Tools

Server Configuration Options

Basic Config (Claude Desktop)

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}

With Custom Host/Port

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"],
      "env": {
        "BLENDER_HOST": "192.168.1.100",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

With Telemetry Disabled

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"],
      "env": {
        "DISABLE_TELEMETRY": "true"
      }
    }
  }
}

Cursor Config

{
  "mcpServers": {
    "blender": {
      "command": "uvx",
      "args": ["blender-mcp"]
    }
  }
}

For platform-specific config details, see our setup guides:

• Claude Desktop setup
• Cursor setup
• VSCode setup

Running Multiple Servers

If you need to switch between AI clients, disconnect from one before connecting with another. The Blender addon’s sidebar panel shows the current connection status.

For advanced use cases where you need multiple AI clients, you could run separate Blender instances on different ports:

• Instance 1: BLENDER_PORT=9876 (default)
• Instance 2: BLENDER_PORT=9877

Each would need its own MCP server config pointing to the correct port.

Performance & Limitations

What Works Well

• Simple object creation and manipulation
• Material and lighting setup
• Poly Haven asset downloads
• Scene inspection and iteration

Known Limitations

• Complex scenes may time out. Break large requests into smaller, sequential prompts.
• Poly Haven integration is unpredictable. Claude sometimes struggles with asset search queries.
• First command may fail. A known quirk — the second message usually works.
• No real-time viewport streaming. The AI works with scene data and screenshots, not a live video feed.
• Blender 2.x is not supported. Requires Blender 3.0 or newer.

Telemetry

BlenderMCP collects anonymous usage data by default. You can control this:

• In Blender: Edit → Preferences → Add-ons → Blender MCP → uncheck telemetry
• Via environment variable: Set DISABLE_TELEMETRY=true

With consent enabled, it collects anonymized prompts, code snippets, and screenshots. Without consent, it collects only tool names, success/failure, and duration.