blender-mirrors/blender_mcp
Watch
3
1
Fork
You've already forked blender_mcp
 0
mirror of https://projects.blender.org/lab/blender_mcp.git synced 2026-08-26 12:41:56 -05:00
Code Issues Projects Releases Packages Wiki Activity
Blender's OFFICIAL MCP server (LLM drives Blender) · GPL · kreeader-studio: authoritative agent→Blender bridge for shot authoring over the /render API
99 commits 1 branch 4 tags 4.2 MiB
  • Python 99.2%
  • Makefile 0.8%
Find a file
Exact
Repository files (latest commit first)
Filename Latest commit message Latest commit date
Campbell Barton 4309a39646 Fix: screenshot size limit didn't account for the JSON envelope 
The limit used the full MCP message size, so an image that just fit
could still exceed the limit once wrapped in JSON.

Reserve 2 KiB headroom.

Ref !38
2026-08-06 12:35:15 +10:00
_misc readme: move generated tool listing to readme_tools.rst 2026-08-06 12:05:17 +10:00
addon Checks: update settings for v0.16 of "ruff check" 2026-08-06 11:41:23 +10:00
chat_client Cleanup: single back ticks in comments 2026-04-23 16:18:47 +10:00
mcp Fix: screenshot size limit didn't account for the JSON envelope 2026-08-06 12:35:15 +10:00
tests Add text-search tools for the bundled docs 2026-04-24 18:43:12 +10:00
.gitignore MCPB files 2026-04-16 14:53:59 +02:00
Makefile readme: move generated tool listing to readme_tools.rst 2026-08-06 12:05:17 +10:00
readme.md readme: move generated tool listing to readme_tools.rst 2026-08-06 12:05:17 +10:00
readme_local_llm.rst Relocate the "mcp" server into ./mcp/ 2026-04-15 12:26:33 +10:00
readme_tools.rst readme_tools: add doc-strings and update 2026-08-06 12:05:23 +10:00

readme.md

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.

Read the documentation at blender.org/lab/mcp-server

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.
  • An MCP server that runs as a separate process, launched by the MCP client (e.g. Llama.cpp).

The data flow is:

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

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.
  • 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/blmcp/, installed as a Python package with the entry point blender-mcp.

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.

mcp/blmcp/data/ Data files bundled with the package.

  • 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/ Each tool is a single module, auto-discovered at startup. Modules ending in _toolcode contain code that runs inside Blender (sent to the addon for execution) and are skipped during discovery.

mcp/blmcp/tools_helpers/ Shared utilities used by tools. Tools should not import from each other; shared logic lives here instead.

Tools

See readme_tools.rst for the tools the MCP server exposes.