Skip to main content
Glama

IMPORTANT

This project is not affiliated with any other Blender MCP project. It is an independent, original codebase — not a fork of, and sharing no code with, anything else. In particular it is unrelated to ahujasid/mcp-for-blender (formerly published on PyPI as blender-mcp). The blender-mcp package on PyPI belongs to that project: installing it does not install this software. Install this project by cloning this repository — see Quick Start.

Provenance: The overall shape — an MCP server talking to a Blender addon over a local socket — is the standard approach for this category of tool and is shared by other Blender MCP projects, so the architectures look similar. This repository is not a fork, and the implementation here is independent.

Overview

Blender MCP AI is an open-source Model Context Protocol server that lets AI assistants control Blender through natural language. It works with any MCP-compatible client — Cursor, Windsurf, Claude Desktop, and more.

The project consists of two components:

  • MCP Server (src/blender_mcp/) — a FastMCP server exposing Blender operations as MCP tools

  • Blender Addon (addon/blender_mcp_addon/) — a Blender plugin that receives commands over TCP and executes them via Blender's Python API

AI Client (Cursor / Windsurf / Claude Desktop)
    ↓  MCP protocol (stdio or HTTP)
Blender MCP Server (Python, FastMCP)
    ↓  TCP JSON messages (localhost:9876)
Blender Addon (runs inside Blender)
    ↓  Blender Python API (bpy)
Blender

Related MCP server: Blender MCP

Generated entirely through natural-language AI commands via Blender MCP AI — no manual Blender interaction.

Stylized character generated end-to-end by the agent through the MCP pipeline

A character built end-to-end by the agent — body template, hair, clothing and accessory — then lit and rendered at 1920×1080 through the MCP tools. It is a deliberately simple primitive-based blockout: the point is the round trip, not the polish.

The point of this project isn't the polish of any single render — it's the agent ↔ Blender pipeline: 380 tools, dynamic skill loading to keep the model's context lean, and viewport/render snapshots that let the model review its own work and iterate.

Key Features

  • 380 MCP tools across 56 modules — modeling, materials, animation, rendering, rigging, and more

  • Smart skill loading — default skill profile starts with 38 tools; 12 skill groups activate on demand to keep AI context lean

  • 6 profiles — from minimal (35 tools) to full (377 tools)

  • Visual feedback — blender_snapshot_viewport and blender_snapshot_render_preview for multimodal AI review loops

  • Checkpoint system — named save/restore points before risky operations

  • Style system — 8 rendering style presets from Pixel Art to AAA

  • 67 procedural materials — metals, woods, stones, fabrics, nature, skin, effects, toon

  • Quality audit — topology, UV, and performance validation

  • Blender 4.x / 5.x compatible

  • Multi-IDE support — Cursor, Windsurf, Claude Desktop, and any MCP client

Quick Start

Prerequisites

  • Python 3.10+

  • Blender 4.0+

  • uv

  • An MCP-compatible client

Install & Run

There is no PyPI release yet. Install from source — pip install blender-mcp would install an unrelated third-party package (see the notice at the top).

git clone https://github.com/harveyxiacn/blender-mcp-ai.git
cd blender-mcp-ai
uv sync

# Build the Blender addon
python build_addon.py

# Start the MCP server
uv run blender-mcp-ai

Set Up Blender

  1. Open Blender → Edit → Preferences → Add-ons → Install...

  2. Select dist/blender_mcp_addon.zip

  3. Enable Blender MCP

  4. Open the MCP panel in the 3D View sidebar

Configure Your IDE

Add to your MCP client config:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blender-mcp-ai", "blender-mcp-ai"]
    }
  }
}

Try It — a guided tour

Want to see what this does before reading anything else? With Blender open and the addon enabled, build a demo scene and inspect it layer by layer:

uv run python scripts/demo_tour.py --clean

It drives the MCP socket 46 times and groups the result into one collection per layer, so you can hide everything except the thing you want to look at:

Collection

What it demonstrates

How to look at it

L1_场景基础

Object creation and transforms

Outliner → select L1_Cube → press N

L2_建模

Bevel / Subdivision / Boolean modifiers

Properties → wrench tab, toggle each modifier

L3_材质

Metal vs plastic, Principled BSDF values

Press Z → Material Preview

L4_灯光相机

Three-point lighting and a camera

Press Z → Rendered; select a light to read its power

L5_UV

Smart UV project

Open a UV Editor, Tab into edit mode, press A

L6_动画

Keyframed bounce + spin

Timeline → press Space

L7_角色骨骼

Generated character plus an armature

Hide other layers, then Pose Mode on L7_Rig

L8_物理

Cloth and rigid-body simulation

Play the timeline

Full step-by-step walkthrough: docs/en/TOUR.md (中文:docs/zh/TOUR.md)

If every layer reports OK, your install works end to end. To check the renderer and exporters too, select L4_Cam and press F12, or run blender_export_fbx on any object.

Running it twice? Pass --clean (as above) so the previous run's objects do not collide with the new names.

Tool Profiles

Profile

Tools

Use Case

minimal

35

Core scene/object/utility/export only

skill

38

Default — core + on-demand skill loading

focused

124

Curated workflow set

standard

186

Broader daily-use coverage

extended

215

Adds physics & batch operations

full

377

Everything

Skill System

With the default skill profile, only core tools load at startup. AI activates additional groups on demand:

blender_list_skills         → see all 12 available skill groups
blender_activate_skill      → load a group's tools dynamically
blender_deactivate_skill    → unload to free AI context

Skills include: modeling, materials, style, character, animation, scene_setup, automation, physics, batch_assets, advanced_3d, sport_character, training.

Documentation

All documentation is available in English and 中文 (Chinese).

Community

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

  1. Fork the repo & create a feature branch

  2. Install dev dependencies: uv sync --all-extras

  3. Make changes and add tests

  4. Run checks: pytest && ruff check src/ && black --check src/

  5. Submit a pull request

Security

For security concerns, please see SECURITY.md. Do not open a public issue for security vulnerabilities.

Known Caveats

  • If .venv breaks after copying the repo to another machine, delete .venv and re-run uv sync

License

MIT — Copyright (c) 2026 Harvey Xia


中文

IMPORTANT

本项目与其他任何同名 Blender MCP 项目均无关联。 这是一套独立、原创的代码库,不是任何项目的 fork,也不共用任何代码。特别地,本项目与 ahujasid/mcp-for-blender(其旧版在 PyPI 上 叫 blender-mcp)毫无关系。PyPI 上的 blender-mcp 属于那个项目,安装它不会安装本软件。 安装本项目请克隆本仓库,见快速开始。

来源说明: 「MCP 服务器 + Blender 插件、走本地 socket」这个整体形态是本类工具的通用做法, 其他 Blender MCP 项目也采用类似结构,因此架构层面看起来会相似。本仓库不是 fork, 实现为独立完成。

概述

Blender MCP AI 是一个开源的 Model Context Protocol 服务器,让 AI 助手可以通过自然语言控制 Blender。支持 Cursor、Windsurf、Claude Desktop 等任意 MCP 兼容客户端。

展示

以下渲染完全通过自然语言 AI 命令生成,无需手动操作 Blender。

由 AI 通过 MCP 管线端到端生成的风格化角色

一个由智能体端到端生成的角色 —— 体型模板、头发、服装、配饰全部由 MCP 工具创建,再经打光与 1920×1080 渲染。它是刻意简化的图元搭建,重点在完整回路,而非精细度。 本项目的价值不在单张渲染的精细度,而在 agent ↔ Blender 管线:380 个工具、动态技能加载以精简上下文、以及让模型自审自迭代的视口/渲染截图。

核心特性

  • 380 个 MCP 工具,覆盖建模、材质、动画、渲染等全流程

  • 智能工具加载 — 默认 skill 配置仅加载 38 个工具,12 个技能组按需激活

  • 6 种配置方案 — 从 minimal(35 个工具)到 full(377 个工具)

  • 视觉反馈 — 视口截图 + 渲染预览,支持多模态 AI 审查循环

  • 检查点系统 — 高风险操作前的命名存档/还原点

  • 风格系统 — 8 种渲染风格预设(像素风到 3A 级)

  • 67 种程序化材质 — 金属、木材、石材、布料、自然、皮肤、特效、卡通

  • 质量审计 — 拓扑、UV、性能验证

  • 兼容 Blender 4.x / 5.x

快速开始

git clone https://github.com/harveyxiacn/blender-mcp-ai.git
cd blender-mcp-ai
uv sync

# 打包 Blender 插件
python build_addon.py

# 启动 MCP 服务器
uv run blender-mcp-ai

目前尚未发布到 PyPI。请从源码安装 —— pip install blender-mcp 装到的是另一个无关的第三方包(见顶部说明)。

然后在 Blender 中:

  1. 编辑 → 偏好设置 → 插件 → 安装...

  2. 选择 dist/blender_mcp_addon.zip

  3. 启用 Blender MCP

  4. 在 3D 视图侧边栏打开 MCP 面板

IDE 配置:

{
  "mcpServers": {
    "blender": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/blender-mcp-ai", "blender-mcp-ai"]
    }
  }
}

上手试一下(分层演示)

想先看看它到底能做什么?保持 Blender 打开、插件已启用,然后运行:

uv run python scripts/demo_tour.py --clean

脚本会通过 MCP socket 执行 46 次调用,并把结果按图层分到各自的集合里,方便你逐层查看:

集合

演示内容

怎么看

L1_场景基础

物体创建与变换

大纲视图选中 L1_Cube,按 N 看变换数值

L2_建模

Bevel / 细分 / 布尔 修改器

右侧扳手图标,逐个开关修改器看差异

L3_材质

金属 vs 塑料、Principled BSDF 参数

按 Z → 材质预览

L4_灯光相机

三点布光 + 相机

按 Z → 渲染预览;选中灯光看功率

L5_UV

Smart UV 展开

打开 UV 编辑器,按 Tab 进编辑模式再按 A

L6_动画

关键帧弹跳 + 自转

时间轴按 空格 播放

L7_角色骨骼

程序生成角色 + 骨架

隐藏其他图层,对 L7_Rig 进姿势模式

L8_物理

布料 + 刚体模拟

播放时间轴

逐层详解请看:docs/zh/TOUR.md(English:docs/en/TOUR.md)

每一层都显示 OK,就说明整套流程跑通了。想连渲染和导出一起验证,选中 L4_Cam 按 F12, 或对任意物体调用 blender_export_fbx。

重复运行时请带上 --clean(如上),否则上一轮的对象会和新的重名冲突。

社区

文档

所有文档均提供 English 和 中文 版本,详见上方文档表格。

系统要求

  • Python 3.10+

  • Blender 4.0+

  • 任意兼容 MCP 的客户端

许可证

MIT — Copyright (c) 2026 Harvey Xia

Available Tools

38 tools
blender_activate_skillA

Activate a skill to dynamically load its tool group.

This registers new MCP tools that become available for immediate use. Each skill provides a set of related tools and a workflow guide.

Use list_skills first to see available skills.

Args: skill_name: Name of the skill to activate (e.g., 'modeling', 'materials', 'animation')

Inputs: skill_name (required). Returns: result

blender_connection_statusA
Read-onlyIdempotent

Query the current connection status and statistics with Blender.

Can be used to diagnose connection issues and confirm whether Blender is online.

Returns: Connection status information

Inputs: params (required). Returns: result

blender_deactivate_skillA

Deactivate a skill, removing its tools to free up context.

Use this when you no longer need a skill's tools, especially before activating a different skill group.

Args: skill_name: Name of the skill to deactivate

Inputs: skill_name (required). Returns: result

blender_describe_hierarchyA
Read-onlyIdempotent

Get the full parent-child object tree of the scene as indented text or JSON.

Example: Show the hierarchy to understand how objects are organized and parented.

Inputs: params (required). Returns: result

blender_describe_objectA
Read-onlyIdempotent

Deep inspection of a single object: topology stats (verts/edges/faces/ngons), material slots, modifier stack, constraints, parent chain, and bounding box.

Example: Inspect 'Cube' to check its polygon count and applied modifiers.

Inputs: params (required). Returns: result

blender_describe_sceneA
Read-onlyIdempotent

Get a structured summary of the current scene: object counts by type, materials, lights, camera, render settings, and frame range.

Example: Describe the scene to understand what objects exist before making changes.

Inputs: params (required). Returns: result

blender_execute_pythonA
Destructive

Execute Python code in Blender.

Note: Use with caution as this may modify the scene or perform dangerous operations.

Args: params: Python code and timeout

Returns: Execution result

Inputs: params (required). Returns: result

blender_export_fbxB
Idempotent

Export as FBX format (suitable for Unity, Unreal, etc.).

Args: params: Export settings

Returns: Export result

Inputs: params (required). Returns: result

blender_export_gltfB
Idempotent

Export as glTF format (suitable for Web, Three.js, etc.).

Args: params: Export settings

Returns: Export result

Inputs: params (required). Returns: result

blender_export_objC
Idempotent

Export as OBJ format.

Args: params: Export settings

Returns: Export result

Inputs: params (required). Returns: result

blender_file_openB
Destructive

Open a Blender file.

Note: This will replace the current scene; unsaved changes will be lost.

Args: params: File path

Returns: Open result

Inputs: params (required). Returns: result

blender_file_saveC
Idempotent

Save the Blender file.

Args: params: File path and compression options

Returns: Save result

Inputs: params (required). Returns: result

blender_get_infoB
Read-onlyIdempotent

Get Blender version and status information.

Returns: Blender info

Inputs: params (required). Returns: result

blender_get_viewport_screenshotC
Read-only

Get a screenshot of the current viewport.

Args: params: Output path and dimensions

Returns: Screenshot path

Inputs: params (required). Returns: result

blender_list_skillsA

List all available skills and their activation status.

Skills are groups of tools that can be loaded on demand. Start here to discover what capabilities are available, then use activate_skill to load the tools you need.

Returns a summary of all skills with their descriptions, tool counts, and current activation status.

Inputs: no named parameters. Returns: result

blender_object_apply_transformA
Idempotent

Apply object transforms (location, rotation, scale).

Applies transform data to the mesh data and resets object transforms to default values.

Args: params: Object name and transform types to apply

Returns: Apply result

Inputs: params (required). Returns: result

blender_object_createB

Create a new object in Blender.

Supports creating various types of objects including meshes (cube, sphere, etc.), curves, text, etc.

Args: params: Object type, name, location, rotation, scale

Returns: Creation result

Inputs: params (required). Returns: result

blender_object_deleteB
Destructive

Delete the specified object.

Args: params: Object name and deletion options

Returns: Deletion result

Inputs: params (required). Returns: result

blender_object_duplicateA

Duplicate an object.

Can create an independent copy or a linked copy (sharing mesh data).

Args: params: Source object name, new name, whether to link, position offset

Returns: Duplication result

Inputs: params (required). Returns: result

blender_object_get_infoB
Read-onlyIdempotent

Get detailed information about an object.

Includes transform, mesh statistics, modifiers, materials, and other info.

Args: params: Object name and inclusion options

Returns: Detailed object information

Inputs: params (required). Returns: result

blender_object_joinC
Destructive

Join multiple objects into one.

Args: params: List of objects to join and target object

Returns: Join result

Inputs: params (required). Returns: result

blender_object_listB
Read-onlyIdempotent

List objects in the scene.

Can filter by type or name pattern.

Args: params: Filter and format options

Returns: Object list

Inputs: params (required). Returns: result

blender_object_parentA
Idempotent

Set the parent-child relationship for objects.

Args: params: Child object and parent object names

Returns: Setting result

Inputs: params (required). Returns: result

blender_object_renameC
Idempotent

Rename an object.

Args: params: Current name and new name

Returns: Rename result

Inputs: params (required). Returns: result

blender_object_selectB
Idempotent

Select objects.

Can select objects by name list or wildcard pattern.

Args: params: Selection parameters

Returns: Selection result

Inputs: params (required). Returns: result

blender_object_set_originA
Idempotent

Set the origin point of an object.

Supports multiple origin setting methods including geometry center, 3D cursor, bottom center (suitable for character feet), etc.

Args: params: Object name and origin type

Returns: Setting result

Inputs: params (required). Returns: result

blender_object_transformB
Idempotent

Transform an object (location, rotation, scale).

Can set absolute values or delta transforms.

Args: params: Object name and transform parameters

Returns: Transform result

Inputs: params (required). Returns: result

blender_redoC

Redo operations.

Args: params: Number of redo steps

Returns: Redo result

Inputs: params (required). Returns: result

blender_scene_createB

Create a new scene in Blender.

Creates a new scene, optionally copied from an existing scene.

Args: params: Contains scene name and optional copy source

Returns: Creation result as JSON string

Inputs: params (required). Returns: result

blender_scene_deleteA
Destructive

Delete the specified scene.

Note: Cannot delete the last remaining scene.

Args: params: Name of the scene to delete

Returns: Deletion result

Inputs: params (required). Returns: result

blender_scene_get_infoA
Read-onlyIdempotent

Get detailed information about a scene.

Returns the scene's frame range, FPS, unit settings, and other detailed info.

Args: params: Scene name (optional)

Returns: Detailed scene information

Inputs: params (required). Returns: result

blender_scene_listA
Read-onlyIdempotent

List all scenes in Blender.

Returns a list of all scenes including name, object count, and other info.

Args: params: Output format options

Returns: Scene list (Markdown or JSON format)

Inputs: params (required). Returns: result

blender_scene_set_settingsB
Idempotent

Set scene settings.

Can set frame range, frame rate, unit system, etc.

Args: params: Scene settings parameters

Returns: Settings result

Inputs: params (required). Returns: result

blender_scene_switchB
Idempotent

Switch to the specified scene.

Args: params: Target scene name

Returns: Switch result

Inputs: params (required). Returns: result

blender_snapshot_render_previewA
Read-onlyIdempotent

Quick render at reduced resolution for preview. Returns the file path.

Example: Render a 512px wide preview with 16 samples to check lighting and materials.

Inputs: params (required). Returns: result

blender_snapshot_viewportA
Read-onlyIdempotent

Capture the 3D viewport as a PNG image. Returns the file path for multimodal AI analysis.

Example: Capture an 800x600 screenshot of the current viewport to see the scene layout.

Inputs: params (required). Returns: result

blender_undoC

Undo operations.

Args: params: Number of undo steps

Returns: Undo result

Inputs: params (required). Returns: result

blender_verify_fbxA
Read-onlyIdempotent

Re-import an exported FBX and assert game-engine readiness.

Checks world origin == (0,0,0), triangle budget, one-object-per-file, and reports materials / emissive slots. Use after blender_export_fbx to self-verify each export instead of post-hoc bulk QA.

Returns: PASS/FAIL with the per-object report.

Inputs: params (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 38 tools

    Disambiguation4/5

    Most tools are clearly distinct, but blender_get_viewport_screenshot and blender_snapshot_viewport have highly overlapping purposes, potentially confusing an agent.

    Naming Consistency5/5

    All tools use a consistent snake_case naming with a clear pattern: resource-specific tools are prefixed with blender_<resource>_ (e.g., blender_object_, blender_scene_) and general actions are blender_<action>_<object>, making the overall pattern predictable.

    Tool Count2/5

    With 38 tools, the count exceeds the 'too many' threshold of 25+. While Blender is complex and the skills system helps, the base set is still large and may overwhelm context windows.

    Completeness3/5

    The base tool set covers core scene and object operations, export, and file I/O, but lacks tools for materials, modifiers, animations, and other essential Blender workflows. The skills system can fill gaps, but as presented, notable operations are missing.

    Maintenance

    ActivitySlowing
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers