BlenderMCP-Blender模型上下文协议集成
BlenderMCP通过模型上下文协议（MCP）将Blender连接到Claude AI，允许Claude直接与Blender交互和控制Blender。这种集成实现了快速辅助的3D建模、场景创建和操纵。
我们没有官方网站。你在网上看到的任何网站都是非官方的，与这个项目没有任何关系。使用它们的风险由你自己承担。
加入社区
提供反馈，获得灵感，并在MCP的基础上进行构建： Discord 的中文翻译是“不和谐”或“纷争”。
支持者
所有支持者：
发行说明（1.2.0）
- 查看Blender视口的屏幕截图，以更好地理解场景
- 搜索并下载Sketchfab模型
以前添加的功能：
- 通过其API支持保利港资产
- 支持使用Hyper3D Rodin生成3D模型
- 对于新手，您可以直接进入安装。对于现有用户，请参阅以下要点
- 下载最新的addon.py文件并替换旧文件，然后将其添加到Blender中
- 从Claude中删除MCP服务器并重新添加，您应该可以使用了！
特性
- 双向通信：通过基于套接字的服务器将Claude AI连接到Blender
- 对象操作：在Blender中创建、修改和删除3D对象
- 材料控制：应用和修改材质和颜色
- 现场检查：获取当前Blender场景的详细信息
- 代码执行：从Claude在Blender中运行任意Python代码
- 🆕 检索工具：具有网格分析、重新网格划分和优化功能的专业修整工作流程
🆕 Retopology功能
BlenderMCP现在包括一套全面的重组工具，用于创建游戏就绪的优化网格：
网格分析
mesh_stats-获取详细的拓扑指标（涵洞/边/面、三元/四边形/ngon计数、表面积、体积）detect_topology_issues-识别非流形边、松散几何体、反转法线和重复项
翻修作业
voxel_remesh-使用统一的基于体素的拓扑重建网格quadriflow_remesh-生成四元主导网格（最适合动画/细分）decimate-在保持形状的同时减少多边形数量（非常适合LOD）shrinkwrap_reproject-将低聚合物网格投影到高聚合物表面
视口和着色
set_view_projection-在正交视图和透视视图之间切换align_view_to_axis-将视图捕捉到前/后/左/右/上/下frame_selected-在视口中框选对象mark_seams_by_angle-基于边缘角度自动标记UV接缝mark_sharp_by_angle-标记锐边以获得适当的阴影
引导式工作流程
- Retopo管道提示 -完整重新定位工作流程的分步指导
有关详细的重新布局工作流程，请参阅 Retopology指南 在......下面
组件
该系统由两个主要部分组成：
- 搅拌机插件(
addon.py)：Blender插件，在Blender中创建套接字服务器以接收和执行命令 - MCP服务器(
src/server.py)：实现模型上下文协议并连接到Blender插件的Python服务器
🏗️ 模块化架构
BlenderMCP遵循干净的模块化架构：
src/
├── server.py # MCP server (import & wrappers only)
├── tools/ # Tool implementations
│ ├── mesh_analysis.py
│ ├── remeshing.py
│ ├── viewport.py
│ ├── shading.py
│ ├── scene.py
│ └── integrations/ # External services
│ ├── polyhaven.py
│ ├── sketchfab.py
│ └── hyper3d.py
└── prompts/ # Guided workflows
├── retopo.py
└── asset_creation.py对于开发者： 看 架构指南 和 重构摘要 有关代码组织以及如何添加新工具的详细信息。
安装
先决条件
- 搅拌机3.0或更新版本
- Python 3.10或更新版本
- uv包管理器：
如果您使用的是Mac，请将uv安装为
brew install uv在Windows上
powershell -c "irm https://astral.sh/uv/install.ps1 | iex" 然后
set Path=C:\Users\nntra\.local\bin;%Path%否则，安装说明在他们的网站上： 安装uv
⚠️ 安装UV之前不要继续
环境变量
以下环境变量可用于配置Blender连接：
BLENDER_HOST：Blender套接字服务器的主机地址（默认：“localhost”）BLENDER_PORT：Blender套接字服务器的端口号（默认值：9876）
例子：
export BLENDER_HOST='host.docker.internal'
export BLENDER_PORT=9876Claude桌面集成
观看设置说明视频 （假设您已经安装了uv）
转到Claude>设置>开发人员>编辑配置>Claude_desktop_Config.json，以包含以下内容：
{
"mcpServers": {
"blender": {
"command": "uvx",
"args": [
"blender-mcp"
]
}
}
}光标集成
对于Mac用户，请转到“设置”>“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 在继续之前安装。
安装Blender插件
- 下载
addon.py此仓库中的文件 - 打开搅拌机
- 转到“编辑”>“首选项”>“附加组件”
- 点击“安装…”并选择
addon.py文件 - 通过选中“接口：Blender MCP”旁边的框启用插件
用法
启动连接
- 在Blender中，转到3D视图侧栏（如果不可见，请按N）
- 找到“BlenderMCP”选项卡
- 如果您希望资产来自其API，请启用Poly Haven复选框（可选）
- 点击“连接到克劳德”
- 确保MCP服务器正在您的终端中运行
与克劳德一起使用
一旦在Claude上设置了配置文件，并且插件在Blender上运行，您将看到一个带有Blender MCP工具的锤子图标。
能力
示例命令
以下是一些你可以要求克劳德做的事情的例子：
- “在地牢中创建一个低多边形场景，龙守卫着一罐金子” 演示
- “使用HDRI、纹理和Poly Haven的岩石和植被等模型营造海滩氛围” 演示
- 给出一个参考图像，并从中创建一个Blender场景 演示
- “通过Hyper3D生成花园侏儒的3D模型”
- 获取当前场景的信息，并从中绘制threejs草图 演示
- “让这辆车变成红色和金属色”
- “创建一个球体并将其放置在立方体上方”
- “让灯光像工作室一样”
- 将相机对准场景，并使其等距
Hyper3D集成
Hyper3D的免费试用密钥允许您每天生成有限数量的模型。如果达到每日限制，您可以等待第二天的重置，或从hyper3d.ai和fal.ai获取自己的密钥。
API密钥和外部服务
BlenderMCP与多个外部服务集成，以提供增强的功能。了解API密钥的工作方式对于生产使用非常重要。
共享试用密钥
重要提示： Blender插件(addon.py)包括Hyper3D Rodin API的共享免费试用密钥：
- 地点：
addon.py第31行(RODIN_FREE_TRIAL_KEY) - 目的： 允许用户无需设置即可测试3D模型生成
- 限制： 所有用户共享，每日发电量限制适用
警告： 此共享密钥用于 仅用于测试和开发.对于生产使用或更重的使用，您应该获得自己的API密钥。
获取您自己的API密钥
对于生产使用或如果您超过免费试用限制，请从以下位置获取个人API密钥：
- Hyper3D罗丹 （人工智能生成的3D模型）
- 网站： hyper3d.ai - 还需要： fal.ai 账户 - 目的：根据文本描述生成3D模型 - 更换钥匙 addon.py 或通过环境变量进行配置
- 保利港湾 （免费3D资源）
- 网站： polyhaven.com - 不需要API密钥（免费的公共API） - 目的：下载HDRI、纹理和3D模型 - 通过Blender插件UI中的复选框启用
- Sketchfab （3D模型市场）
- 网站： sketchfab.com - 目的：搜索和下载3D模型 - API访问：可能需要帐户才能实现全部功能
安全最佳实践
- 永远不要提交个人API密钥 到版本控制
- 使用环境变量 用于生产部署
- 定期旋转按键 如果它们被暴露
- 监控使用情况 检测未经授权的访问
- 将试用密钥分开 从生产密钥
对于开发者
如果您正在通过其他外部服务集成扩展BlenderMCP：
- 将API密钥存储在环境变量中，而不是硬编码在源代码中
- 在自述文件中记录所需的API密钥
- 为用户获取自己的密钥提供明确的说明
- 考虑为API调用实现速率限制和错误处理
Retopology指南
BlenderMCP包括一个全面的重组工具包，用于从高多边形源创建游戏就绪的优化网格。
有关详细的工作流程、工具参考和最佳实践，请参阅 Retopology指南.
快速开始
最简单的开始方法是使用 Retopo管道 提示：
Use the "retopo_pipeline" prompt to guide me through retopologizing this meshBDD测试规范
所有重组功能都记录在行为驱动开发（BDD）规范中 features/ 目录：
01_mcp_contract.feature-MCP工具/资源/提示发现02_mesh_analysis.feature-拓扑度量和问题检测03_voxel_remesh.feature-基于体素的重网格化04_quadriflow_remesh.feature-四重优势重网格05_decimation.feature-多边形缩减06_shrinkwrap.feature-表面投影07_seams_shading.feature-UV接缝和锐边标记08_viewport_controls.feature-查看投影和对齐
这些特征文件既是重新定位系统的规范，也是文档。
故障排除
- 连接问题：确保Blender插件服务器正在运行，并且MCP服务器已在Claude上配置，不要在终端中运行uvx命令。有时，第一个命令不会执行，但之后它就开始工作了。
- 超时错误：尝试简化您的请求或将其分解为更小的步骤
- Poly-Haven整合克劳德有时行为古怪
- 你试过把它关掉再打开吗？：如果您仍然存在连接错误，请尝试重新启动Claude和Blender服务器
技术细节
通信协议
该系统在TCP套接字上使用简单的基于JSON的协议：
- 命令 以JSON对象的形式发送
type可选params - 回复 JSON对象具有
status和result或message
限制和安全考虑
- 这
execute_blender_code该工具允许在Blender中运行任意Python代码，这可能很强大，但有潜在的危险。在生产环境中小心使用。在使用之前，一定要保存好你的工作。 - Poly Haven需要下载模型、纹理和HDRI图像。如果您不想使用它，请在Blender中的复选框中将其关闭。
- 复杂的操作可能需要分解为更小的步骤
测试
BlenderMCP包括一个全面的测试套件，包括 真实集成测试 它运行在一个无头Blender实例上。
看 测试/README.md 有关运行测试的详细说明。
快速启动测试
# Run all tests (including mocked unit tests)
pytest tests/
# Run real integration tests (requires local Blender installation)
pytest tests/integration/ -v贡献
欢迎投稿！请随时提交拉取请求。
免责声明
这是一个第三方集成，不是由Blender制作的。由……制造 西达尔特