Blender

快速开始

注意： PyPI 包 blender-mcp 现在名为 mcp-for-blender。现有配置仍可正常使用——uvx blender-mcp 仍会运行服务，无需更改配置。新安装请使用 mcp-for-blender。 变更内容及原因

一条命令即可为你的 AI 应用和 Blender 插件完成设置：

macOS / Linux

curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

Windows（PowerShell）

irm https://www.mcp-for-blender.com/install.ps1 | iex

也可在命令提示符中运行：powershell -c "irm https://www.mcp-for-blender.com/install.ps1 | iex"

不想运行脚本，或脚本被 Windows Defender 拦截？使用 winget 安装 uv，打开新终端，然后运行设置命令：

winget install --id=astral-sh.uv -e
uvx mcp-for-blender setup

已经安装 uv？请改为运行 uvx mcp-for-blender setup。

如果需要，它会安装 uv，查找你计算机上的 MCP 客户端（Claude Desktop、Claude Code、Codex、Cursor、VS Code、Devin Desktop/Windsurf、OpenCode、Antigravity），并让你选择要配置的客户端。随后，它会安装 Blender 插件并将其启用。你的现有配置会保留：它只会添加一个 blender 条目，并为每个修改的文件保存一个 .bak 备份。

然后完全退出并重新打开 AI 应用（在 Windows 上，请从系统托盘退出），打开 Blender，并让它帮你构建内容。Blender 启动时，插件会启动服务。

# macOS
brew install uv

# Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
winget install --id=astral-sh.uv -e
# or, with uv's installer
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

claude mcp add blender uvx mcp-for-blender

codex mcp add blender -- uvx mcp-for-blender

uvx mcp-for-blender install-addon

注意： 只运行一个 MCP 服务实例（Cursor 或 Claude Desktop），不要同时运行两者。

目录

• 快速入门
• 功能
• 高级版
• 组件
• 安装
  • 自动设置
  • 先决条件
  • 让客户端找到 uvx
  • 固定 Python 版本
  • 不使用 uv 安装
  • 使用 Docker 运行
  • 环境变量
• MCP 客户端设置
  • Claude for Desktop
  • Codex
  • Cursor
  • Visual Studio Code
  • OpenCode
  • Antigravity
• 安装 Blender 插件
• 升级（现有用户）
• 用法
  • 启动连接
  • 与 Claude 配合使用
  • 功能
  • 示例命令
• 持久化 API 凭据
• 故障排除
• 技术详情
• 限制与安全注意事项
• 遥测控制
• 反馈
• 参与贡献
• 免责声明
• Star 历史

功能

高级版

无需自备 API 密钥，即可直接在 Blender 中生成 AI 3D 模型（Meshy、Hunyuan3D、Tripo、Hyper3D Rodin）。了解详情

组件

系统由两个主要组件构成：

1. Blender 插件（addon.py）——一个在 Blender 内创建套接字服务以接收并执行命令的 Blender 插件
2. MCP 服务（src/blender_mcp/server.py）——一个实现 Model Context Protocol 并连接到 Blender 插件的 Python 服务

安装

自动设置

最快的方法是一行安装程序。它会安装 uv、配置 MCP 客户端，并安装和启用 Blender 插件：

# macOS / Linux
curl -LsSf https://www.mcp-for-blender.com/install.sh | sh

# Windows (PowerShell)
irm https://www.mcp-for-blender.com/install.ps1 | iex

已经安装 uv？请改为运行 uvx mcp-for-blender setup。在 Windows 上，运行 winget install --id=astral-sh.uv -e 即可安装 uv，无需运行脚本。有关它会修改哪些内容，请参阅快速入门。本节其余内容介绍手动设置。

先决条件

• Blender 3.0 或更高版本
• Python 3.10 或更高版本
• uv 包管理器

brew install uv

winget install --id=astral-sh.uv -e

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

$localBin = "$env:USERPROFILE\.local\bin"
$userPath = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$userPath;$localBin", "User")

curl -LsSf https://astral.sh/uv/install.sh | sh

警告： 安装 uv 之前，请勿继续。

让客户端找到 uvx

从图形界面启动的 MCP 客户端（Claude Desktop、Cursor、从程序坞／开始菜单启动的 VS Code）不会继承终端的 PATH，因此即使 uvx 在终端中可以正常运行，裸写 "command": "uvx" 也可能失败，并报错 spawn uvx ENOENT。如果遇到这种情况：

• 查找 uvx 的完整路径——使用 which uvx（macOS/Linux）或 where uvx（Windows），并将其用作 "command"，例如 /opt/homebrew/bin/uvx 或 C:\Users\<you>\.local\bin\uvx.exe。
• 在 Windows 上，也可以用以下命令包装："command": "cmd", "args": ["/c", "uvx", "mcp-for-blender"]。
• 更改 PATH 或配置后，请彻底退出并重新启动客户端（Windows：从系统托盘退出，而不仅仅是关闭窗口；macOS：按 Cmd+Q）。

固定 Python 版本

避免 conda / pyenv / 版本冲突。

uv 会选择运行服务的 Python。在安装了 conda（会自动激活 base）、pyenv 或 asdf 的计算机上，或者使用某些依赖尚未提供 wheel 的较新 CPython 版本时，uv 可能会选用导致安装失败的解释器。固定使用 Python 3.11，并优先选择由 uv 管理的解释器，以避免使用 PATH 中的任意解释器：

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "mcp-for-blender"],
            "env": { "UV_PYTHON_PREFERENCE": "only-managed" }
        }
    }
}

--python 3.11 仍满足此软件包的 requires-python >=3.10，而 UV_PYTHON_PREFERENCE=only-managed 可防止 uv 优先选择 conda、pyenv、asdf 或系统 Python。（仓库中的 .python-version 只是给贡献者的提示，不会影响 uvx。）

如果之前失败的尝试在修复后仍不断重放，请清除缓存：

uv cache clean mcp-for-blender blender-mcp && uvx --refresh mcp-for-blender

不使用 uv 进行安装

在受限计算机上，可以完全跳过 uvx，改用 pipx，然后让客户端指向已安装的命令：

pipx install mcp-for-blender
pipx ensurepath          # then restart your shell / client

将生成的绝对路径用作 "command"（使用 which mcp-for-blender / where mcp-for-blender 查找），并省略 args。

使用 Docker 运行

你可以在容器中运行 MCP 服务，而不必安装它。Blender 本身仍在你的计算机上运行——容器仅承载 MCP 服务，该服务会连接到 Blender 插件。

从仓库根目录构建镜像：

docker build -t mcp-for-blender .

然后让 MCP 客户端使用该镜像（必须使用 -i 标志——服务通过 stdin/stdout 与客户端通信）：

{
    "mcpServers": {
        "blender": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "mcp-for-blender"]
        }
    }
}

在 macOS 和 Windows 上使用 Docker Desktop 时，镜像默认设置的 BLENDER_HOST=host.docker.internal 可以直接连接主机上的 Blender。

在 Linux 上，host.docker.internal 不存在，而且插件只监听 localhost，因此请改用主机网络：

{
    "mcpServers": {
        "blender": {
            "command": "docker",
            "args": ["run", "-i", "--rm", "--network=host", "-e", "BLENDER_HOST=localhost", "mcp-for-blender"]
        }
    }
}

若要在容器中启用安全模式，请在 args 中添加 "-e", "BLENDER_MCP_SAFE_MODE=1"。

环境变量

以下环境变量可用于配置 Blender 连接：

示例：

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

也可以通过 CLI 标志传递连接配置，这些标志的优先级高于环境变量。这样便于同时运行多个 Blender 实例，因为每个 MCP 客户端条目都可以通过普通参数指向不同端口，而无需使用环境变量：

uvx mcp-for-blender --port 9877

在 MCP 客户端配置中，这意味着添加第二个条目，且仅 args 不同：

{
  "mcpServers": {
    "blender": { "command": "uvx", "args": ["mcp-for-blender"] },
    "blender-b": { "command": "uvx", "args": ["mcp-for-blender", "--port", "9877"] }
  }
}

每个实例都需要在 Blender 插件面板中设置各自的端口，以确保匹配。

注意： 插件的套接字服务没有身份验证或加密，因此任何能够访问该端口的人都可以在 Blender 中运行 Python。除非处于可信网络，否则请将其限制在 localhost；与其直接将 --host/BLENDER_HOST 指向远程计算机，不如优先使用 SSH 隧道。

安全模式

默认情况下，AI 可以在 Blender 中运行任意 Python 代码。设置 BLENDER_MCP_SAFE_MODE=1，即可在每个脚本运行前进行检查并阻止危险代码，例如直接读取或写入文件、运行其他程序、访问网络，或安装会在脚本结束后继续运行的代码。常规 Blender 工作（建模、材质、渲染、保存、导入/导出）仍可正常进行。被阻止的脚本会连同原因一起返回给 AI，以便它尝试修正后再次运行。

MCP 客户端设置

Claude for Desktop

观看设置说明视频（假设你已安装 uv）

前往 Claude → Settings → Developer → Edit Config → claude_desktop_config.json，并添加以下内容：

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

claude mcp add blender uvx mcp-for-blender

Codex

Codex CLI、桌面应用和 IDE 扩展共用同一个配置文件（~/.codex/config.toml），因此设置一次服务即可供这三者使用。

Codex 插件（推荐）

该插件会在聊天中内嵌实时视口（点击对象即可将其附加到下一条消息），提供 Poly Haven、Sketchfab 和 Poly Pizza 的缩略图选择器，以及场景对象、材质和集合的 @ 提及功能。它目前尚未加入 Codex 插件目录，因此请从此仓库添加：

git clone https://github.com/ahujasid/blender-mcp.git
codex plugin marketplace add ./blender-mcp/integrations/codex

然后重启 Codex，从插件目录安装 MCP for Blender，并在聊天中让它使用 MCP for Blender。运行后，视口会在对话旁边的侧面板中打开：

纯 MCP 服务

使用 Codex CLI 注册此服务：

codex mcp add blender -- uvx mcp-for-blender

也可以手动将其添加到 ~/.codex/config.toml（或 $CODEX_HOME/config.toml）：

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]

也可以在 Codex 桌面应用中操作：依次选择 Settings → MCP servers → Add server → 将其命名为 blender，选择 STDIO，在命令栏中输入 uvx mcp-for-blender，然后点击 Save 并重启。如果应用找不到 uvx，请改用其完整路径，参见让客户端找到 uvx。

运行 codex mcp list 检查是否已注册——blender 服务应显示为已启用。下次启动 Codex 时即可使用这些工具。

若要设置环境变量（例如，使用非默认的 Blender 主机/端口），请将 --env KEY=VALUE 标志传递给 codex mcp add，或将其添加到配置文件中：

[mcp_servers.blender]
command = "uvx"
args = ["mcp-for-blender"]
env = { BLENDER_HOST = "localhost", BLENDER_PORT = "9876" }

Cursor

macOS — 前往 Settings → MCP，粘贴以下内容：

• 若要将其用作全局服务，请点击 "add new global MCP server" 按钮并粘贴
• 若要将其用作项目专属服务，请在项目根目录下创建 .cursor/mcp.json 并粘贴

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

Windows — 前往 Settings → MCP → Add Server，使用以下设置添加新服务：

{
    "mcpServers": {
        "blender": {
            "command": "cmd",
            "args": [
                "/c",
                "uvx",
                "mcp-for-blender"
            ]
        }
    }
}

Cursor 设置视频

注意： 只能运行一个 MCP 服务实例（在 Cursor 或 Claude Desktop 上运行），不要同时运行两者。

Visual Studio Code

前提条件：请先确认已安装 Visual Studio Code。

OpenCode

{
  "mcp": {
    "blender-mcp": {
      "type": "local",
      "command": ["uvx", "mcp-for-blender"],
      "enabled": true,
      "environment": {
        "BLENDER_HOST": "localhost",
        "BLENDER_PORT": "9876"
      }
    }
  }
}

Antigravity

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

安装 Blender 插件

uvx mcp-for-blender setup（参见快速入门）会完成所有这些操作，包括启用插件。以下步骤适用于手动安装。

1. 建议方式 — 在终端中运行：

uvx mcp-for-blender install-addon

此操作会将插件复制到 Blender 插件文件夹，并命名为 blender_mcp.py。它会显示文件的写入位置，并为替换的文件保留 .bak 备份。

可选：uvx mcp-for-blender addon-paths 会列出检测到的 Blender 插件文件夹。使用 BLENDERMCP_ADDONS_DIR=/path/to/scripts/addons 可覆盖目标路径。

2. 打开 Blender

3. 前往 Edit → Preferences → Add-ons

4. 启用 Interface: MCP for Blender（搜索 "MCP for Blender"）。如果暂时没有显示，请点击 Install… 并选择复制的 blender_mcp.py / addon.py，或重启 Blender。

5. 手动替代方式 — 如果上述命令找不到 Blender 安装位置，或你更愿意手动操作：从此仓库下载 addon.py → 在 Blender 中依次选择 Edit → Preferences → Add-ons → Install… → 选择下载的 addon.py → 启用它。

然后打开 Blender 侧栏中的 MCP for Blender 选项卡（在 3D 视口中按 N），并点击 Start MCP Server。请参见下文的启动连接。

升级（现有用户）

新用户请直接前往快速开始。现有用户请看下文。

1. 运行：

uvx mcp-for-blender@latest update

这会更新 MCP 服务（刷新 uv 的缓存副本，或升级通过 uv tool install 安装的版本），并更新每个已安装的 Blender 插件副本，同时为每个被替换的文件保留一个 .bak 备份。它绝不会将版本高于此发行版的插件降级，也不会改动你在本地编辑过的副本。添加 --dry-run 可先查看它会进行哪些更改。

第一次请使用 @latest：早于 2.1.7 的发行版没有 update 命令，而且 uvx 可能仍缓存着其中一个旧版本。

2. 重启 MCP 客户端（Claude Desktop、Cursor，……），以便启动新版服务。

3. 在 Blender 中：重启 Blender，或前往 Preferences → Add-ons，先停用再重新启用 Interface: MCP for Blender，然后再次点击 Start MCP Server。

如果客户端仍使用旧的 blender-mcp 软件包名称进行配置，update 会提示你；运行 uvx mcp-for-blender setup 即可切换。

**注意：**MCP 服务绝不会自行修改 Blender 插件文件。启动时，它会检查已安装的插件是否落后于随附版本，并记录更新方法；实际写入文件的是 update 和 install-addon。旧版已加载插件仍可通过 execute_code 后备方式进行轨迹采集。

使用方法

启动连接

1. 在 Blender 中，打开 3D 视图侧边栏（如果未显示，请按 N）
2. 找到 MCP for Blender 选项卡
3. 勾选你想使用的选项（更多内容请参见下文的功能）
4. 点击 Connect to Claude
5. 确认终端中的 MCP 服务正在运行

与 Claude 搭配使用

在 Claude 中设置好配置文件并在 Blender 中运行插件后，你会看到一个锤子图标，其中包含 MCP for Blender 的工具。

功能

AI 会自行编写 Blender Python，用于建模、布局、材质、动画、绑定和重拓扑。MCP 补充了 Python 无法独立完成的功能，提供以下九种工具：

Tencent Cloud 上的 Hunyuan3D（官方 API 模式）

插件必须调用的 Tencent Cloud 服务取决于你的账号所属区域：

将国际版凭据发送到中国大陆端点会触发 AuthFailure.SignatureFailure 或 ResourceUnavailable 错误，因此，如果你的 SecretId/SecretKey 来自 tencentcloud.com，请勾选此开关。 该开关位于侧边栏的腾讯混元 3D → 官方 API下方。

Meshy

Meshy 可根据文本提示词或参考图像生成带纹理的 3D 模型， 并将模型调整为真实世界的高度、原点置于底部，因此模型会以合理的尺寸直立在地面上。 你可以通过 Premium 使用 Meshy，无需密钥；也可以使用自己的 Meshy API 密钥。 通过 Premium 使用 Meshy 时，会采用其最新模型，并且每个模型计为一次标准生成。 使用自己的 API 密钥需要 Meshy 付费方案： 获取 Meshy API 密钥。 使用自己的密钥时，要求生成一个“采用 A 姿势”或“采用 T 姿势”的角色，Meshy 就会按该姿势生成角色，可直接用于绑定。

Poly Haven

Poly Haven 提供约 2,400 个 HDRI、纹理和模型， 全部采用 CC0 许可且免费，靠捐赠而非出售资源获得资金支持。无需 API 密钥、账号，也不必担心速率限制。

在 3D 视图侧边栏中，勾选Poly Haven即可。设置到此完成。

示例：

“使用阴天午后的 HDRI 为场景布光，并在墙面上添加锈蚀金属纹理”

Claude 会调用 search_assets(source="polyhaven", query="overcast afternoon", asset_type="hdris")， 该工具会理解意图，而不是只匹配关键词——搜索“沙发”也能找到长沙发，并且支持任何语言。previews=3 会在消耗带宽前附上排名靠前结果的缩略图，而 import_asset(source="polyhaven", id="...", asset_type="textures", apply_to=["Wall"]) 则会通过一次调用下载纹理并应用它。

搜索也可以按类别路径筛选，或按 HDRI 的天气、时段等属性筛选，或按纹理的表面用途、状况等属性筛选；如果属性无效，则会报错并列出有效属性。

模型从 .blend 文件导入，该文件是艺术家创作的源文件——glTF、 FBX 和 USD 版本均由它生成，并会丢失材质细节。纹理会根据其所用贴图构建 Principled 材质，并跳过无人读取的重新打包版本和其他格式约定。HDRI 会打包到文件中，因此即使保存后在其他位置重新打开，照明效果也能保留；它们会载入新的世界环境，而不会覆盖你创建的环境。

许可与署名： Poly Haven 的所有资源均采用 CC0 许可。无论出于何种用途，无论是否用于商业用途，你都不必注明任何人的姓名。不过，其 API 条款要求基于实时 API 构建的软件明确说明资源来源，因此搜索和导入响应会注明来源并链接到资源页面。导入时，polyhaven_id、 polyhaven_url、polyhaven_authors、polyhaven_resolution 和 polyhaven_licence 会作为自定义属性写入导入的对象、材质、图像和世界环境中，因此之后打开 .blend 文件的人仍能找到资源及其创作者。

Poly Pizza

Poly Pizza 收录了约 10,600 个免费的低多边形模型，其中包括抢救下来的 Google Poly 归档内容。它是获取风格化游戏素材的最佳来源：每个模型都是独立完整的 .glb 文件，几何体也比 Sketchfab 的轻量得多。

1. 在 poly.pizza/settings/api 获取免费的 API 密钥
2. 在 3D 视图侧边栏中勾选 Use assets from Poly Pizza
3. 将密钥粘贴到显示的 API Key 字段中（也可以通过 编辑 → 偏好设置 → 插件 → MCP for Blender 永久保存）

示例：

“在 Poly Pizza 中搜索一把采用 CC0 许可的低多边形椅子，并以 1 米高导入”

Claude 会调用 search_assets(source="polypizza", query="chair", licence="CC0")，该调用会返回每个匹配项的许可和三角形数量，然后调用 import_asset(source="polypizza", id="...", target_size=1.0)。

你也可以按类别筛选（"Animals"、"Furniture & Decor"、"Transport"、 "Nature"、"Buildings"、"People & Characters"、"Food & Drink"、"Weapons"、 "Clutter"、"Objects"、"Scenes & Levels"、"Other"），或只查找带动画的模型。

署名： Poly Pizza 目录中约 69% 的内容采用 CC-BY 许可，要求你在模型出现的任何地方标注创作者。导入时，格式完备的署名信息会作为自定义属性 polypizza_attribution 写入每个导入的根对象（同时还会写入 polypizza_id 和 polypizza_licence），因此这些信息会保存在你的 .blend 文件中，并在会话结束后保留。如果你想使用无需署名的模型，可以通过 licence="CC0" 筛选。

示例命令

以下是一些你可以让 Claude 执行的操作示例：

持久保存 API 凭据

MCP for Blender 支持通过 Blender 插件偏好设置持久保存凭据：

编辑 → 偏好设置 → 插件 → MCP for Blender

你可以在此处保存以下值，使其在 Blender 重启后仍然可用：

• Sketchfab API 密钥
• Poly Pizza API 密钥
• Hyper3D API 密钥
• Hunyuan3D SecretId / SecretKey
• Hunyuan3D API URL
• Meshy API 密钥

对于无头环境或 CI，也可以通过环境变量注入凭据：

故障排除

技术细节

通信协议

系统通过 TCP 套接字使用简单的基于 JSON 的协议：

• 命令以 JSON 对象的形式发送，其中包含 type 和可选的 params
• 响应是 JSON 对象，其中包含 status 和 result 或 message

限制与安全注意事项

警告：execute_blender_code 工具允许在 Blender 中运行任意 Python 代码，功能强大，但也可能存在危险。在生产环境中请谨慎使用。使用前务必保存你的工作。

• Poly Haven 需要下载模型、纹理和 HDRI 图像。如果你不想使用它，请在 Blender 的复选框中将其关闭。
• 复杂操作可能需要拆分成更小的步骤。

遥测控制

遥测功能默认关闭。默认情况下不会收集你的内容，除非你明确启用，否则它会一直保持关闭。

**默认收集的内容（无需选择加入）：**一条最精简的匿名使用记录，用于统计活跃用户并了解哪些工具被使用——随机生成的安装 ID、会话 ID、工具名称、是否成功、耗时、MCP for Blender 和 Blender 版本、你的操作系统，以及时间戳。

**未选择加入时绝不收集：**你的提示词、生成的代码、视口截图、场景数据和轨迹步骤。

选择加入——前往 Edit → Preferences → Add-ons → MCP for Blender，勾选遥测同意复选框。一些 MCP 客户端也会在对话开始时向你提供一次性选择加入提示。选择加入后，收集内容将包括提示词、生成的代码、截图和轨迹数据；详情请参阅 TnC。你可以随时在同一位置将其关闭。

若要完全关闭遥测（包括最精简的匿名使用记录），请设置环境变量：

DISABLE_TELEMETRY=true uvx mcp-for-blender

或者将其添加到 MCP 配置中：

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

遥测数据不会与你的姓名或账户关联。数据可能用于改进 MCP for Blender、开展研究以及训练 AI 模型。

有关收集内容的完整详情，以及你选择加入时授予的许可，请参阅 TERMS_AND_CONDITIONS.md。

反馈

我们正在积极征集关于 MCP for Blender 的反馈。如果你有任何想法，请在这里分享。

如果你有更详细的反馈，可以在这里与我们预约通话——我们会在项目中致谢。

加入社区

提供反馈、获取灵感，并基于 MCP 进行构建：Discord

贡献

欢迎贡献！请随时提交 Pull Request。

免责声明

这是第三方集成，并非由 Blender 制作。由 Siddharth 制作。

Star 历史