ClaudeKit Blender MCP

ClaudeKit Blender MCP

Model Context Protocol server for Blender 3D integration with ClaudeKit enhancements.

Installation • Configuration • Tools • Troubleshooting

______________________________________________________________________

特性

• 🎨 26搅拌机工具：从Claude Desktop完全控制Blender
• 🎭 对象管理：创建、修改、变换对象
• 🎬 场景控制：管理场景、相机、照明
• 📦 资产一体化：从Poly Haven、Sketchfab等进口
• 🖼️ 视口控制：截图，渲染场景
• 🔧 材料和纹理管理：完整的素材编辑功能
• 📝 Python脚本：执行自定义Blender脚本

安装

选项1：全球安装（生产使用）

npm install -g claudekit-blender-mcp

方案2：地方发展

# Clone the repository
git clone https://github.com/yourusername/claudekit-blender-mcp.git
cd claudekit-blender-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

第一步：安装Blender插件

1. 打开搅拌机
2. 首选 Edit → 偏好设置→ 附加组件
3. 点击 安装。.. 按钮
4. 导航到并选择： blender-addon/addon.py
5. 通过选中旁边的框启用插件 “Blender MCP服务器”

Blender启动时，插件将自动启动WebSocket服务器。

步骤2：配置Claude桌面

配置文件位置因操作系统而异：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

全局安装配置

{
  "mcpServers": {
    "blender": {
      "command": "npx",
      "args": ["-y", "claudekit-blender-mcp"]
    }
  }
}

本地开发配置

如果使用节点版本管理器（fnm、nvm、asdf）：

{
  "mcpServers": {
    "blender": {
      "command": "/absolute/path/to/node",
      "args": ["/absolute/path/to/claudekit-blender-mcp/dist/index.js"]
    }
  }
}

找到你的Node.js路径：

# For fnm users
which node  # Then use realpath or readlink to get actual path

# For nvm users
nvm which current

# Example paths:
# fnm: /Users/username/.local/share/fnm/node-versions/v20.19.5/installation/bin/node
# nvm: /Users/username/.nvm/versions/node/v20.19.5/bin/node

如果Node.js在系统PATH中：

{
  "mcpServers": {
    "blender": {
      "command": "node",
      "args": ["/absolute/path/to/claudekit-blender-mcp/dist/index.js"]
    }
  }
}

步骤3：重新启动克劳德桌面

重要提示： 您必须完全重新启动Claude Desktop（而不仅仅是重新加载）：

# macOS
killall "Claude" && sleep 2 && open -a "Claude"

# Windows
# Close Claude Desktop completely from system tray, then reopen

# Linux
killall claude && claude

验证

测试连接

打开Claude Desktop并尝试以下命令：

What MCP tools do you have available?
List all Blender tools
Create a cube in Blender

预期输出

您应该看到26个可用工具：

核心搅拌机工具（10）：

• blender_execute_python：在Blender中执行Python代码
• blender_create_object：创建对象（立方体、球体等）
• blender_list_objects：列出场景中的所有对象
• blender_modify_object：修改对象属性
• blender_delete_object：删除对象
• blender_get_scene_info：获取场景信息
• blender_render_scene：渲染当前场景
• blender_save_file：保存.blend文件
• blender_take_screenshot：捕获视口
• blender_import_file：导入三维文件

资产集成工具（16）：

• polyhaven_search_assets：搜索Poly Haven图书馆
• polyhaven_get_asset_info：获取资产详细信息
• polyhaven_download_asset：下载资产
• 还有更多。..

故障排除

错误： spawn node ENOENT

问题： Claude Desktop找不到 node 命令。

解决方案： 在配置中使用Node.js的绝对路径。

# Find your Node.js path
which node
realpath $(which node)  # Get the actual path if using fnm/nvm

# Update config with absolute path
# Example:
{
  "mcpServers": {
    "blender": {
      "command": "/Users/username/.local/share/fnm/node-versions/v20.19.5/installation/bin/node",
      "args": ["/path/to/project/dist/index.js"]
    }
  }
}

为什么会发生这种情况：

• Claude Desktop使用自己的PATH环境运行
• 节点版本管理器（fnm、nvm、asdf）修改shell PATH
• Claude Desktop的PATH不包括这些自定义路径
• 解决方案：使用绝对路径绕过path查找

MCP服务器未连接

1.检查克劳德桌面日志：

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
# Check: %APPDATA%\Claude\logs\

# Linux
tail -f ~/.config/Claude/logs/mcp*.log

2.验证Blender插件是否正在运行：

• 打开搅拌机→ 窗口→ 切换系统控制台
• 查找：“BlenderMCP服务器在本地主机9876上启动”

3.手动测试MCP服务器：

# For local development
cd /path/to/claudekit-blender-mcp
node dist/index.js

# Should see:
# Starting ClaudeKit Blender MCP Server...
# Registered 10 core Blender tools
# Registered 16 asset integration tools

JSON配置错误

验证您的配置文件：

# macOS/Linux
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

# Should output formatted JSON without errors

常见错误：

• 条目之间缺少逗号
• 对象/数组末尾的尾随逗号
• 报价类型不正确（使用 " 不 ')
• 缺少闭合括号

搅拌机连接超时

检查Blender插件状态：

1. 搅拌机→ Edit → 偏好设置→ 附加组件
2. 搜索“MCP”
3. 确保复选框已选中
4. 检查控制台是否有错误

防火墙问题：

• 确保允许本地主机连接
• 默认端口：9876
• 协议：TCP套接字

未找到模块错误

对于当地发展：

cd /path/to/claudekit-blender-mcp
npm install  # Reinstall dependencies
npm run build  # Rebuild

检查Node.js版本：

node --version  # Should be >= 18.0.0

发展

项目结构

claudekit-blender-mcp/
├── src/
│   ├── server.ts          # MCP server setup
│   ├── tools/             # Tool implementations
│   │   ├── objects.ts     # Object manipulation
│   │   ├── scene.ts       # Scene management
│   │   ├── materials.ts   # Material system
│   │   ├── assets.ts      # Asset integration
│   │   └── ...
│   └── utils/             # Utilities
├── dist/                  # Compiled JavaScript
├── blender-addon/
│   └── addon.py          # Blender addon
└── docs/                 # Documentation

开发工作流程

# Watch mode (auto-rebuild on changes)
npm run dev

# Build once
npm run build

# Clean build
npm run clean && npm run build

# After making changes:
# 1. Rebuild: npm run build
# 2. Restart Claude Desktop
# 3. Test changes

运行测试

# Run all tests (coming soon)
npm test

# Test specific tool
npm test -- objects

可用工具

核心搅拌机操作

• 对象管理：创建、修改、删除、变换对象
• 场景控制：管理场景、相机、照明
• 视口：截图，改变视角
• 渲染：渲染图像和动画
• 文件I/O：导入/导出各种3D格式

资产一体化

• 聚天堂：搜索和下载HDRI、纹理、模型
• Sketchfab：浏览和导入模型
• 外部来源：自定义资产来源

高级功能

• 材料编辑：创建和修改材质
• 纹理管理：应用和管理纹理
• Python脚本：执行自定义Blender脚本
• 批量操作：处理多个对象

需求

• Node.js: >= 18.0.0
• 搅拌机：>=3.0（用3.6+测试）
• 克劳德桌面版：最新版本
• 操作系统：macOS、Windows或Linux

给终端用户的提示

最佳实践

1. 在使用Claude Desktop之前，请务必启动Blender
2. 保持Blender控制台打开 查看实时反馈
3. 经常保存您的工作 -使用“保存Blender文件”
4. 使用描述性名称 使对象易于参考
5. 从简单的命令开始 验证连接

示例工作流

创建场景：

1. "Create a cube in Blender"
2. "Add a sphere 5 units above the cube"
3. "Create a camera looking at the objects"
4. "Add a sun light to the scene"
5. "Take a screenshot of the viewport"

使用材料：

1. "Create a red metallic material"
2. "Apply it to the cube"
3. "Make the sphere glass-like"

资产整合：

1. "Search for HDRI sky on Poly Haven"
2. "Download the first result"
3. "Set it as environment texture"

支持

获取帮助

• 文档：检查 /docs 详细指南文件夹
• 问题：报告GitHub问题上的错误
• 日志：始终先检查Claude Desktop日志

报告Bug

包括：

1. 克劳德桌面版
2. Node.js版本(node --version)
3. 搅拌机版本
4. 操作系统和版本
5. 配置文件内容（删除敏感数据）
6. 来自Claude Desktop的错误日志
7. 搅拌机控制台输出

贡献

欢迎投稿！拜托：

1. 复刻仓库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

致谢

• 内置于 模型上下文协议
• 与集成 聚天堂
• 由...驱动 搅拌机

______________________________________________________________________

由...制作❤️ ClaudeKit团队