# Blender MCP插件安装避坑指南：从Python环境配置到Claude联动全流程 ## 1. 环境准备与前置检查 在开始安装Blender MCP插件之前，确保系统满足以下基础要求： - **Blender版本**：3.0或更高（推荐3.6 LTS） - **Python版本**：3.10.x（必须精确匹配） - **操作系统权限**：管理员/root权限 **常见版本冲突案例**： ```plaintext 错误示例：ImportError: cannot import name 'Literal' from 'typing' 原因：Python版本低于3.8导致类型注解不兼容 ``` > 提示：使用`blender --version`和`python --version`命令验证版本，若存在多版本Python，建议通过pyenv管理。 ## 2. Python环境配置详解 ### 2.1 独立环境搭建 为避免系统Python污染，推荐创建虚拟环境： ```bash # macOS/Linux python3.10 -m venv ~/blender_mcp_env source ~/blender_mcp_env/bin/activate # Windows python3.10 -m venv C:\blender_mcp_env C:\blender_mcp_env\Scripts\activate ``` ### 2.2 UV包管理器安装 UV是MCP的核心依赖管理工具，安装时需注意： | 操作系统 | 安装命令 | 验证方式 | |---------|---------|---------| | macOS | `brew install uv` | `uv --version` | | Windows | `powershell -c "irm https://astral.sh/uv/install.ps1 \| iex"` | 检查环境变量 | **典型报错处理**： - *"uv: command not found"* → 手动添加`~/.local/bin`到PATH - *证书验证失败* → 临时关闭防火墙或使用代理镜像源 ## 3. Blender插件安装实战 ### 3.1 插件文件获取 从官方仓库克隆最新代码： ```bash git clone https://github.com/ahujasid/blender-mcp.git cd blender-mcp ``` ### 3.2 加载插件步骤 1. 启动Blender，进入`Edit > Preferences > Add-ons` 2. 点击"Install..."选择`addon.py` 3. 勾选`Interface: Blender MCP`复选框 **加载失败排查清单**： - 检查控制台是否有Python语法错误 - 确认blender-mcp目录未被其他进程锁定 - 尝试以管理员身份运行Blender ## 4. Claude桌面端配置 修改`claude_desktop_config.json`的完整示例： ```json { "mcpServers": { "blender": { "command": "/usr/local/bin/uvx", "args": ["blender-mcp"], "env": { "BLENDER_HOST": "127.0.0.1", "BLENDER_PORT": "9876" } } } } ``` 关键参数说明： - `command`：uvx可执行文件绝对路径 - `args`：固定为`blender-mcp` - `env`：可覆盖默认连接参数 ## 5. 连接测试与故障排除 ### 5.1 服务启动流程 1. 在Blender侧边栏(N键)点击"Start MCP Server" 2. 观察终端输出： ```plaintext [INFO] Socket server started on port 9876 [DEBUG] Waiting for client connection... ``` ### 5.2 常见错误代码速查表 | 错误码 | 可能原因 | 解决方案 | |-------|---------|---------| | ECONNREFUSED | 端口被占用 | 修改BLENDER_PORT环境变量 | | ETIMEDOUT | 防火墙拦截 | 添加9876端口白名单 | | ENOENT | uvx路径错误 | 使用`which uvx`确认位置 | ## 6. 高级调试技巧 ### 6.1 日志级别调整 在Blender Python控制台输入： ```python import logging logging.basicConfig(level=logging.DEBUG) ``` ### 6.2 网络抓包分析 使用Wireshark过滤TCP端口9876流量，检查JSON报文结构是否符合协议规范。 ## 7. 性能优化建议 - **内存管理**：为Blender分配至少4GB专用内存 - **GPU加速**：在Edit > System设置CUDA后端 - **缓存清理**：定期执行`uv cache clean` 实际项目中，这些配置帮助我将指令响应时间从3.2秒降低到800毫秒。特别是在处理复杂场景时，合理的资源分配能显著提升稳定性。