Blender MCP

Overview

A lightweight MCP (Model Context Protocol) server for Blender. It offers a natural language interface with Blender's Python API, improving access to documentation, and allowing users to explore and understand complex setups.

Fork repository: git.sharkk.net/sky/blender_mcp

---

The project is deliberately small, maintainable, and does no more than necessary. It has two components that communicate over a TCP socket:

• A Blender add-on that runs inside Blender and executes requests.
• A Go MCP server that runs as a separate process, launched by the MCP client.

The data flow is:

MCP Client  ⇐ MCP/stdio ⇒  blender-mcp  ⇐ TCP socket ⇒  Blender Add-on

Build and Install Pipeline

The local pipeline builds the Go MCP server, packages the Python Blender extension, installs/enables it in Blender, saves add-on connection preferences, and writes a harness config that can launch the MCP server.

BLENDER_PATH=/Applications/Blender.app/Contents/MacOS/Blender make pipeline

Outputs:

• dist/blender-mcp: standalone Go MCP server binary.
• dist/mcp-*.zip: Blender extension zip.
• dist/mcp-harness-config.json: generic MCP harness config using the built binary and current Blender bridge environment.

Useful targets:

• make build: build the server, add-on zip, and harness config without installing into Blender.
• make install_addon: build, install, enable, and configure the add-on.
• make harness_config: write only the harness config after building the server.
• make run_mcp: build and run the MCP server locally.

Pipeline variables:

• BLENDER_PATH: Blender executable used by the installer and server.
• BLENDER_MCP_HOST / BLENDER_MCP_PORT: add-on socket endpoint saved into Blender preferences and exported to harness config.
• BLENDER_MCP_PROGRESS_INTERVAL: how often the MCP server emits progress heartbeats while Blender is still working (default 10s).
• BLENDER_MCP_AUTOSTART_DELAY: saved add-on autostart delay (default 0.0 for harness readiness).
• BLENDER_EXTENSION_REPO: Blender extension repo name (default user_default).
• SERVER_BIN / HARNESS_CONFIG: override output paths.

After installing, open Blender with online access enabled so the add-on can auto-start its local socket bridge, then point your MCP harness at dist/mcp-harness-config.json or launch dist/blender-mcp directly.

Blender Add-on

Located in addon/blender_mcp_addon/.

A Blender extension that allows the MCP server to communicate with a running Blender instance. It must be installed and enabled for any of the MCP tools to work.

The add-on provides a preferences panel for configuring the host, port, and an optional auto-start setting.

Functionality Overview

Note that this is intended to be a fairly minimal add-on.

Connectivity

• Auto-start (optional), is non-blocking any issues can be viewed from the preferences.
• Configurable polling intervals (active and idle rates) from preferences to avoid excessive overhead.
• Client timeout protection - stalled connections are evicted after 5 minutes; request payloads may be up to 50 MiB.
• Start/stop operators accessible from the preferences panel.
• Deferred responses are supported only by the interactive add-on server; background mode requires requests to complete synchronously and rejects deferred results.

MCP Server

Located in mcp/ and implemented in Go with only the standard library. During development, run it with go run ./mcp from the repository root or build the pipeline binary with make build_go.

An MCP client launches this process and communicates with it over stdio. The server connects to the add-on's TCP socket to relay requests to Blender. It accepts standard MCP Content-Length stdio framing and the lightweight newline-delimited JSON-RPC framing used by the integration tests. For deferred Blender actions, the add-on sends pending frames while the socket stays open; the Go server converts those frames to MCP progress notifications when the client provides a progress token, then returns the final tool result. While Blender is busy and cannot send add-on progress frames, the Go server emits heartbeat progress notifications every BLENDER_MCP_PROGRESS_INTERVAL so MCP clients know the tool is still running.

mcp/blmcp/data/ Data files embedded into the Go server binary.

• prompts.yml provides instructions sent to the LLM at connection time.
• api/ contains Blender Python API reference in RST format.
• manual/ contains Blender user manual excerpts in RST format.

mcp/blmcp/tools/ Python tool-code that runs inside Blender. The Go server embeds the *_toolcode.py files, wraps them with the shared calling convention, and sends them to the add-on for execution.

mcp/blmcp/tools_helpers/ Legacy Python helpers kept for tests and reference while the Go server owns runtime MCP serving.

Tools

• execute_blender_code
  • Execute Python code in the connected Blender instance, or in blender --background when blend_file is provided.
• inspect_blender
  • Fetch blend-file summaries for paths, data-blocks, missing files, linked libraries, use guesses, objects, or one object detail.
• capture_blender_view
  • Capture the Blender UI as a window PNG, area PNG, or structured window JSON.
• navigate_blender
  • Move Blender's UI focus to a workspace, editor, object, or object data-block.
• render_blender
  • Render a viewport image or fast thumbnail to a path.
• get_python_api_docs
  • Return the Blender Python API docs for identifier, or list modules matching a trailing-* discovery pattern.
• search_blender_docs
  • Search the bundled Python API docs, user manual, or both.

Set BLENDER_MCP_TOOL_PROFILE=full to expose the legacy specific tool names alongside the compact defaults for older clients.