快速开始

三个步骤：安装 uv，将您的 MCP 客户端指向服务器，安装 Blender 插件。

1. 安装 uv

# macOS
brew install uv

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

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

警告： 在安装 uv 之前请勿继续。请使用官方安装程序——不要使用 pip install uv。

2. 将 MCP 服务器添加到您的客户端

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

claude mcp 添加 blender uvx blender-mcp

codex mcp 添加 blender -- uvx blender-mcp

3.安装Blender插件

uvx blender-mcp install-addon

然后在 Blender 中：编辑 → 首选项 → 插件 → 启用 界面：Blender 的 MCP。

4. 连接

在 Blender 的 3D 视图中，按 N → 打开 Blender 的 MCP 选项卡 → 点击 启动 MCP 服务器。就是这样 — 请 Claude 构建一些东西。

注意: 仅运行 一个 MCP 服务器实例（光标或 Claude 桌面其中之一），不要同时运行。

特征

组件

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

1. Blender 插件（addon.py）——一个在 Blender 中创建套接字服务器以接收和执行命令的 Blender 插件
2. MCP 服务器（src/blender_mcp/server.py）——一个实现模型上下文协议并连接到 Blender 插件的 Python 服务器

安装

前提条件

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

brew install uv

powershell -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

警告： 安装紫外线前请勿继续。

让你的客户找到UVX

从 GUI（Claude Desktop、Cursor、Dock/开始菜单中的 VS Code）启动的 MCP 客户端不会继承你的终端的 PATH，所以单独使用 "command": "uvx" 可能会因为 spawn uvx ENOENT 而失败，即使在你的终端中 uvx 可以正常工作。如果发生这种情况：

• 找到 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", "blender-mcp"]。
• 在更改任何PATH或配置后，完全退出并重新启动客户端（Windows：从系统托盘退出，而不仅仅是窗口;macOS：按Cmd Q）。

钉住Python版本

避免 conda / pyenv / 版本冲突。

uv 会选择哪个 Python 来运行服务器。在带有 conda（自动激活基站）、pyenv 或 asdf 的机器上，或者使用一些依赖尚未支持的新 CPython 版本，uv 可以抓取一个解释器，导致安装失败。将 Python 3.11 固定，并偏好 uv 管理的解释器，以避免使用路径上的内容：

{
    "mcpServers": {
        "blender": {
            "command": "uvx",
            "args": ["--python", "3.11", "blender-mcp"],
            "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 blender-mcp && uvx --refresh blender-mcp

无需 uv 安装

在受限制的机器上，你可以完全跳过 uvx，使用 pipx，然后将你的客户端指向已安装的命令：

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

使用生成的绝对路径作为 "command"（通过 which blender-mcp / where blender-mcp 找到）并省略 args。

使用 Docker 运行

您可以在容器中运行 MCP 服务器，而无需安装它。Blender 本身仍然在您的机器上运行——容器仅托管 MCP 服务器，该服务器连接到 Blender 插件。

从仓库根目录构建镜像：

docker build -t blender-mcp .

然后将你的 MCP 客户端指向它（需要使用 -i 标志——服务器通过 stdin/stdout 与客户端通信）：

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

该镜像默认使用 BLENDER_HOST=host.docker.internal，在 macOS 和 Windows 上使用 Docker Desktop 时，可以开箱即用地访问主机的 Blender。

在 Linux 上，host.docker.internal 不存在，插件只能监听 localhost，所以请改用主机网络：

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

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

环境变量

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

示例：

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

安全模式

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

MCP 客户端安装

Claude 桌面版

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

进入 Claude → 设置 → 开发者 → 编辑配置 → claude_desktop_config.json 并包含以下内容：

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

claude mcp 添加 blender uvx blender-mcp

法典

Codex CLI、桌面应用程序和 IDE 扩展都共享相同的配置文件（~/.codex/config.toml），因此设置一次服务器即可覆盖三者。

使用 Codex CLI 注册服务器：

codex mcp add blender -- uvx blender-mcp

或者手动将其添加到 ~/.codex/config.toml（或 $CODEX_HOME/config.toml）:

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

或者在Codex 桌面应用中：设置 → MCP 服务器 → 添加服务器 → 命名为 blender，选择 STDIO，输入命令 uvx blender-mcp，然后 保存 并重启。如果应用找不到 uvx，请使用其完整路径 — 参见 让你的客户端找到 uvx。

检查它是否注册成功，使用 codex mcp list — blender 服务器应该显示为 已启用。工具将在下次启动 Codex 时可用。

To set environment variables (e.g. a non-default Blender host/port), pass --env KEY=VALUE flags to codex mcp add, or add them in the config file:

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

光标

macOS — 进入 设置 → MCP 并粘贴以下内容：

• 要作为全局服务器使用，请点击 "添加新的全局 MCP 服务器" 按钮并粘贴
• 要作为项目特定服务器使用，请在项目根目录下创建 .cursor/mcp.json 并粘贴

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

Windows — 进入 设置 → MCP → 添加服务器，使用以下设置添加新服务器：

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

光标设置视频

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

Visual Studio 代码

前提条件：在继续之前，请确保已安装 Visual Studio Code。

打开代码

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

反重力

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

安装 Blender 插件

1. 推荐 — 在终端中运行：

uvx blender-mcp install-addon

这会将插件复制到你的 Blender 插件文件夹中，命名为 blender_mcp.py。它会显示写入的位置，并保留任何被替换文件的 .bak 备份。

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

2. Open Blender

3. 进入 编辑 → 首选项 → 插件

4. 启用 界面：Blender MCP（搜索 “MCP for Blender”）。如果尚未显示，点击 安装… 并选择复制的 blender_mcp.py / addon.py，或重启 Blender。

5. 手动方式 — 如果上述命令无法找到你的 Blender 安装，或者你更喜欢手动操作：从此仓库下载 addon.py → 在 Blender 中，编辑 → 首选项 → 插件 → 安装… → 选择下载的 addon.py → 启用它。

然后在 Blender 侧边栏（在 3D 视图中按 N）打开 MCP for Blender 标签，并点击 启动 MCP 服务器。参见下方 启动连接。

升级（已有用户）

对于新用户，请直接前往 快速开始。对于已有用户，请见下文。

1. 通过运行以下命令更新插件文件：

uvx blender-mcp install-addon
uvx blender-mcp addon-paths   # optional: list detected Blender addons folders

2. 在 Blender 中：首选项 → 插件 → 禁用并重新启用 Interface: MCP for Blender（或重启 Blender），然后再次点击 启动 MCP 服务器。

3. 如果服务器包本身需要刷新，请从 Claude 删除 MCP 服务器并重新添加。

注意： MCP 服务器自身从不修改你的 Blender 插件文件。当它启动时，会检查已安装的插件是否落后于捆绑副本，并记录如何更新；install-addon 才是真正进行写入的操作，并会保留它替换的文件的 .bak 文件。通过 execute_code 回退机制，轨迹捕捉仍然可以在旧插件上工作。

使用方法

开始连接

1. 在 Blender 中，进入 3D 视图侧边栏（如果未显示，请按 N）
2. 找到 Blender 的 MCP 选项卡
3. 勾选您想使用的复选框（更多信息请参见下方的 功能）
4. 点击 连接到 Claude
5. 确保 MCP 服务器在终端中运行

与 Claude 一起使用

配置文件在 Claude 上设置完成，并且 Blender 插件正在运行后，您将看到带有 Blender MCP 工具的锤子图标。

功能

• 获取场景和对象信息
• 创建、删除和修改形状
• 为对象应用或创建材质
• 在 Blender 中执行任何 Python 代码
• 通过 Poly Haven 下载合适的模型、资源和 HDRIs
• 从 Sketchfab 搜索和下载模型
• 从 Poly Pizza 搜索和下载低多边形模型
• 通过 Hyper3D Rodin 和 Hunyuan3D 生成 AI 3D 模型

多利比萨

Poly Pizza 托管了大约 10,600 个免费的低多边形模型，包括恢复的 Google Poly 归档。它是获取风格化游戏资源的最佳来源：每个模型都是独立的 .glb 文件，并且几何结构比 Sketchfab 的更轻。

1. 在 poly.pizza/settings/api 获取免费的 API 密钥
2. 在 3D 视图侧边栏中，勾选 使用 Poly Pizza 的资源
3. 将密钥粘贴到出现的 API 密钥 字段中（或永久存储在 编辑 → 首选项 → 插件 → Blender 的 MCP 下）

示例操作：

“在 Poly Pizza 上搜索低多边形椅子，需 CC0 许可，并以 1 米高导入一个”

Claude 调用 search_polypizza_models(query="chair", licence="CC0")，返回每个匹配项及其许可和三角面数量，然后调用 download_polypizza_model(model_id="...", normalize_size=True, 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 凭证

Blender 的 MCP 通过 Blender 插件偏好设置支持持久化凭证：

编辑 → 首选项 → 插件 → MCP for Blender

你可以在此存储这些值，以便在 Blender 重启后仍然有效：

• Sketchfab API 密钥
• Poly Pizza API 密钥
• Hyper3D API 密钥
• 混元3D SecretId / SecretKey
• 混元3D API URL

对于无界面设置或持续集成 (CI)，凭证也可以通过环境变量注入：

故障排除

技术细节

通信协议

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

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

限制 & 安全考虑

警告： execute_blender_code 工具允许在 Blender 中运行任意 Python 代码，这非常强大，但潜在危险。在生产环境中使用时请谨慎。使用前请务必保存您的工作。

• Poly Haven 需要下载模型、纹理和 HDRI 图像。如果您不想使用，请在 Blender 中取消勾选该选项。
• 复杂操作可能需要分解为更小步骤。

遥测控制

Blender 的 MCP 收集匿名使用数据以帮助改进工具。遥测默认是 开启 的，您可以通过两种方式关闭它：

1. 在 Blender 中 — 进入 编辑 → 首选项 → 插件 → MCP for Blender 并取消勾选遥测同意框。

• 已同意（勾选，默认）：查看条款以了解收集的数据详情。

2. 环境变量 — 通过运行以下命令可以完全禁用所有遥测：

DISABLE_TELEMETRY=true uvx blender-mcp

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

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

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

关于收集的详细信息，以及你开启遥测时授予的许可，请参阅 TERMS_AND_CONDITIONS.md。

反馈

我们正在积极寻找关于 Blender 的 MCP 的反馈。如果您有想法，请在这里分享。

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

加入社区

提供反馈，获得灵感，并在 MCP 基础上进行创作：Discord

贡献

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

免责声明

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

星际历史