blender mcp claude CLI使用教程

直接通过自然语言让AI操作Blender并非魔法，而是基于标准化的MCP（Model Context Protocol）协议实现的进程间通信。核心判断在于：你必须同时运行一个支持MCP的Blender插件服务端和一个能够发起MCP请求的Claude CLI客户端，两者通过本地套接字或标准输入输出流交换JSON-RPC消息。如果缺少其中任何一环，或者版本协议不匹配，连接必然失败。本教程聚焦于如何在本地环境中打通这一链路，并解释数据是如何从你的提示词转化为Blender中的网格顶点。

为什么连接总是超时或拒绝

大多数初次尝试者遇到的第一个障碍不是代码写错，而是环境隔离导致的通信阻断。Blender作为一个独立的图形应用程序，默认并不监听外部API请求。MCP的作用就是充当翻译官，它需要在Blender内部运行一个Python脚本作为Server，暴露特定的工具接口（如create_cube, set_material）。

Blender内部Python控制台输出MCP服务就绪信息

常见的失败因果链如下：

1. Blender未启动或脚本未加载：客户端发送请求时，没有进程在监听对应的端口或STDIN，导致Connection Refused。
2. Python环境冲突：Blender内置的Python版本与系统全局Python版本不一致，导致MCP依赖库（如pydantic或mcp包）无法在Blender内部正确导入。
3. 权限限制：在某些操作系统中，CLI工具试图访问Blender的临时目录或套接字文件时被安全策略拦截。

要验证这一点，不要直接运行复杂的生成命令。先在Blender的Python控制台中手动执行MCP服务端的初始化代码，观察是否有报错日志。如果控制台打印出“Server started on port ...”或类似就绪信息，说明服务端正常；否则，问题出在Blender内部的依赖安装上。

MCP协议如何映射Blender操作

理解机制才能调试。MCP基于JSON-RPC 2.0标准，这意味着每一次交互都是严格的“请求-响应”模式。当你在Claude CLI中输入“创建一个红色的立方体”时，LLM并不会直接画图，而是先调用MCP定义的tools/list获取可用工具，然后构造一个符合Schema的tools/call请求。

MCP协议中JSON-RPC消息在CLI与Blender间的流转

这个请求会被序列化为JSON字符串，通过STDIN发送给Blender端的MCP Server。Blender端的Python脚本接收到JSON后，解析出方法名和参数，再调用原生的bpy.ops.mesh.primitive_cube_add()和材质分配逻辑。执行完成后，它将结果（成功状态或错误信息）封装回JSON，通过STDOUT返回给CLI。

关键在于Schema的定义。如果MCP Server没有正确声明某个工具的参数类型（例如将颜色定义为字符串而非RGB元组），LLM生成的调用参数就会格式错误，导致Blender端抛出异常。因此，检查MCP服务的capabilities和tools定义是排查逻辑错误的第一步。

以下是一个简化的MCP工具定义示例，展示了如何将Blender操作暴露给AI：

from mcp.server.fastmcp import FastMCP
import bpy

mcp = FastMCP("BlenderController")

@mcp.tool()
def create_cube(name: str, location: list[float]):
    """在指定位置创建一个立方体"""
    bpy.ops.mesh.primitive_cube_add(location=location)
    obj = bpy.context.active_object
    obj.name = name
    return f"Created cube {name} at {location}"

if __name__ == "__main__":
    mcp.run()

注意，location参数被明确定义为list[float]。如果LLM传入的是字符串"[0,0,0]"，反序列化会失败。这就是为什么在测试阶段，必须严格对照文档检查参数类型。

构建稳定的CLI工作流

一旦通信链路打通，接下来的挑战是如何让Claude CLI稳定地调用这些工具。你需要在Claude CLI的配置文件中注册Blender MCP Server。通常是在claude_desktop_config.json或类似的配置文件中添加一个mcpServers条目。

在配置文件中注册Blender MCP服务器

配置示例如下：

{
  "mcpServers": {
    "blender": {
      "command": "python",
      "args": ["/path/to/blender_mcp_server.py"],
      "env": {
        "BLENDER_PATH": "/Applications/Blender.app/Contents/MacOS/Blender"
      }
    }
  }
}

这里有一个隐蔽的陷阱：command指向的Python解释器必须能够访问Blender的Python库，或者你的MCP Server脚本是通过Blender自带的Python运行的。更稳健的做法是编写一个Shell脚本作为中介，该脚本先启动Blender后台模式（--background），再加载MCP脚本，确保环境一致性。

在实际操作中，建议采用分步验证策略：

1. 连通性测试：使用简单的ping或get_scene_info工具，确认CLI能收到Blender的响应。
2. 只读操作：先尝试获取当前场景的对象列表，避免误修改场景。
3. 写入操作：逐步引入创建物体、修改属性等写操作，并每次检查Blender视图中的变化。

如果在CLI中看到“Tool execution failed”但Blender端无报错，检查STDOUT是否被其他日志污染。MCP协议要求STDOUT仅用于JSON通信，任何print()调试信息都会破坏JSON解析，导致客户端认为响应无效。务必将调试日志重定向到STDERR或文件。

何时不应该使用MCP

虽然MCP提供了灵活的集成方式，但它并非万能。对于高频、实时的交互（如视口拖动时的实时预览），JSON-RPC的序列化开销和网络延迟会导致明显的卡顿。此时，直接编写Blender原生Python脚本或通过OSC（Open Sound Control）协议进行轻量级通信可能更高效。

此外，如果涉及复杂的几何计算或大规模场景修改，LLM生成的代码往往缺乏优化，可能导致Blender内存溢出。在这种情况下，应让LLM生成高层级的操作指令（如“应用细分表面修改器”），而不是让它逐顶点操作。

掌握MCP的核心在于理解其作为“胶水层”的定位：它负责标准化通信，但不解决业务逻辑的复杂性。保持工具接口的原子性和幂等性，是构建可靠AI-3D工作流的关键原则。