项目介绍
Nuke-MCP
Nuke-MCP 是一个使用模型上下文协议（MCP）连接 The Foundry 的 Nuke 和 AI 系统的桥梁。
概述
Nuke-MCP 允许 AI 助手通过套接字连接与 Nuke 进行交互，使它们能够：
- 获取关于 Nuke 脚本的信息
- 创建、修改和删除节点
- 在节点图中定位节点
- 连接节点
- 控制播放和渲染
- 在 Nuke 中执行任意 Python 代码
组件
- Nuke 插件 (
nuke_mcp_addon.py)：在 Nuke 内创建套接字服务器的 Nuke 脚本。 - MCP 服务器 (
nuke_mcp_server.py)：一个 Python 服务器，连接到 Nuke 插件并向 AI 系统暴露工具。 - 入口点 (
main.py)：一个简单的脚本以启动 MCP 服务器。
安装
预备条件
- The Foundry 的 Nuke（任何较新的版本应该都可以工作）
- Python 3.7+
- FastMCP 包
- Claude Desktop
安装 FastMCP 包
pip install fastmcp
安装 Nuke-MCP
- 克隆或下载此仓库。
- 将
nuke_mcp_addon.py文件复制到您的 Nuke 脚本文件夹或 Nuke Python 路径中的位置。
使用
安装 Nuke 插件
-
复制插件文件：
- 将
nuke_mcp_addon.py文件放置在 Nuke 可找到的位置：- 复制到您的 Nuke 脚本文件夹（通常在 Linux/Mac 上是
~/.nuke/python或 Windows 上的家目录） - 或者放在 Nuke Python 路径中的文件夹内
- 复制到您的 Nuke 脚本文件夹（通常在 Linux/Mac 上是
- 将
-
创建启动脚本（推荐）：
- 在您的
.nuke目录中创建或编辑现有的init.py文件 - 添加以下行以自动加载插件，确保您指向了存放 MCP 工具的 python 子文件夹：
nuke.pluginAddPath("./python") import nuke_mcp_addon
- 在您的
-
手动加载（替代方案）：
- 如果不想自动加载，可以每次手动加载：
- 打开 Nuke
- 确保在 init.py 中设置了 python 子文件夹，其中存放 MCP 工具
- 前往脚本编辑器面板
- 运行
import nuke_mcp_addon
- 如果不想自动加载，可以每次手动加载：
锚定 NukeMCP 面板
默认情况下，NukeMCP 面板作为浮动窗口打开。如果您希望将其锚定在 Nuke 的界面中，可以修改 nuke_mcp_addon.py 中的 NukeMCPPanel 类：
# 查找 NukeMCPPanel 类定义（大约在第 380 行）
class NukeMCPPanel(nukescripts.PythonPanel):
def __init__(self):
nukescripts.PythonPanel.__init__(self, 'Nuke MCP', 'com.example.NukeMCP')
# ... 现有代码 ...
# 添加此方法以启用锚定
def addToPane(self):
pane = nuke.getPaneFor('Properties.1')
if not pane:
pane = nuke.getPaneFor('Viewer.1')
self.setMinimumSize(300, 200) # 设置合理的最小尺寸
return pane.addPermanentAsQWidget(self)
# 修改 show_panel 函数以使用锚定
def show_panel():
"""显示 NukeMCP 面板"""
global _panel
if _panel is None:
_panel = NukeMCPPanel()
# 显示为锚定面板而不是浮动窗口
pane = _panel.addToPane()
if pane:
_panel.setParent(pane)
您还可以修改面板在菜单中的显示方式。基于您的 menu.py 文件，您有：
# MCP 工具
nuke.toolbar("Nodes").addCommand('NukeMCP/NukeMCP 面板', 'nuke_mcp_addon.show_panel()')
为了确保它正确集成到您的现有工具栏结构中，请确保在您的 menu.py 文件中取消注释这一行。
故障排除
要使用 Nuke-MCP 与 Claude Desktop 一起工作，请遵循以下步骤：
-
下载并安装 Claude Desktop：
- 从 Anthropic 的网站下载 Claude Desktop
- 安装并设置您的账户
-
启用开发者模式：
- 打开 Claude Desktop
- 前往设置
- 启用开发者模式（这可能需要特定权限）
-
编辑配置文件：
- 在 Claude Desktop 设置中点击“编辑配置”（或直接编辑
claude_desktop_config.json文件） - 添加 Nuke-MCP 服务器配置：
- 在 Claude Desktop 设置中点击“编辑配置”（或直接编辑
{
"mcpServers": {
"nuke": {
"command": "python",
"args": [
"/path/to/your/nuke-mcp/main.py"
],
"trusted": true
}
}
}
-
替换路径：
- 更新路径为您保存
main.py文件的实际路径 - 确保使用完整的绝对路径
- 对于 Windows，使用正斜杠或转义反斜杠：
或"args": ["Z:/path/to/nuke_mcp/main.py"]"args": ["Z:\\path\\to\\nuke_mcp\\main.py"] - 注意：
"trusted": true标志对于完全功能是必需的
- 更新路径为您保存
-
重启 Claude Desktop：
- 保存配置文件
- 重启 Claude Desktop 应用更改
现在当您使用 Claude Desktop 时，您可以指示它通过 MCP 连接与 Nuke 进行交互。
系统架构
该系统由三个主要组件组成，协同工作：
- Nuke 插件：在 Nuke 内运行，并创建监听命令的套接字服务器
- MCP 服务器：作为 AI 系统和 Nuke 之间的中间件
- AI 客户端：连接到 MCP 服务器以控制 Nuke（例如 Claude Desktop）
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ │ │ │ │ │
│ AI 客户端 │◄───►│ MCP 服务器 │◄───►│ Nuke 插件 │
│ (Claude) │ │ │ │ (在 Nuke 内) │
│ │ │ │ │ │
└─────────────┘ └─────────────┘ └─────────────┘
可用工具
MCP 服务器暴露了以下工具：
get_script_info()：获取当前 Nuke 脚本的信息get_node_info(node_name)：获取特定节点的详细信息create_node(node_type, name, position, inputs, parameters)：创建新节点modify_node(name, parameters, position, inputs)：更改现有节点delete_node(name)：删除节点position_node(name, x, y)：在节点图中定位节点connect_nodes(output_node, input_node, input_index)：连接节点render(frame_range, write_node, proxy_mode)：渲染帧viewer_playback(action, start_frame, end_frame)：控制查看器播放execute_nuke_code(code)：在 Nuke 中运行 Python 代码auto_layout_nodes(selected_only)：自动排列节点set_frames(first_frame, last_frame, current_frame)：设置帧范围create_viewer(input_node)：创建查看器节点
示例
创建一个简单的模糊节点
create_node(node_type="Blur", parameters={"size": 10})
构建一个分级节点链
create_node(node_type="Read", name="input", parameters={"file": "/path/to/image.exr"})
create_node(node_type="Grade", name="grade1", position=[200, 0])
create_node(node_type="Grade", name="grade2", position=[400, 0])
create_node(node_type="Write", name="output", position=[600, 0], parameters={"file": "/path/to/output.exr"})
connect_nodes(output_node="input", input_node="grade1")
connect_nodes(output_node="grade1", input_node="grade2")
connect_nodes(output_node="grade2", input_node="output")
渲染输出
render(frame_range="1-10", write_node="output")
用于 Claude 的示例命令
当与 Claude Desktop 一起工作时，您可以给它自然语言指令来控制 Nuke。这里有一些示例命令：
基本脚本分析
"你能告诉我我的当前 Nuke 脚本里有什么吗？"
创建一个完整的合成设置
"在 Nuke 中创建一个带有读取节点、色彩校正、分级和写入节点的合成设置，所有节点都正确连接。"
构建绿幕抠像设置
"在 Nuke 中创建一个专业的绿幕抠像设置，包括抠像、去溢色、边缘模糊和背景上的合成。"
添加特殊效果
"使用噪声、粒子发射器和合并节点在 Nuke 中构建一个粒子系统，以创建火焰效果。"
增强现有脚本
"分析我当前的 Nuke 脚本，然后通过创建一个分别调整阴影、中间调和高光的色彩分级链来增强它。添加微妙的胶片颗粒效果和柔和的晕影。"
3D 场景设置
"在 Nuke 中设置一个带有相机、3D 对象和适当照明的 3D 场景。"
扩展 MCP 工具
您可以通过向 nuke_mcp_server.py 文件添加新工具来扩展系统。MCP 工具使用 @mcp.tool() 装饰器模式定义。
工具结构
每个工具遵循以下基本结构：
@mcp.tool()
def tool_name(ctx: Context, param1: type, param2: type = default_value) -> str:
"""
工具描述用于文档。
参数：
- param1: param1 的描述
- param2: param2 的描述，具有默认值
"""
try:
logger.info(f"调用工具：tool_name，参数")
nuke = get_nuke_connection()
result = nuke.send_command("command_name", {
"param1": param1,
"param2": param2
})
# 处理结果并格式化响应
return "人类可读的响应"
except Exception as e:
logger.error(f"错误在 tool_name：{str(e)}")
return f"错误消息：{str(e)}"
添加新工具
要添加新工具：
-
确定您想要添加的功能
-
在 Nuke 插件中添加新方法（在
nuke_mcp_addon.py中）：- 将方法添加到
NukeMCPServer类中 - 在
execute_command方法的handlers字典中添加条目
- 将方法添加到
-
在
nuke_mcp_server.py中创建相应的工具：- 使用
@mcp.tool()装饰器 - 定义带有类型提示的参数
- 添加描述性文档字符串
- 实现逻辑以调用相应的 Nuke 命令
- 使用
-
彻底测试新工具
示例：添加一个变换节点工具
这是一个如何添加一个创建变换节点的专用工具的例子：
@mcp.tool()
def create_transform(
ctx: Context,
name: str = None,
position: List[int] = None,
rotation: float = 0.0,
scale: float = 1.0,
center: List[float] = None
) -> str:
"""
使用指定参数创建变换节点。
参数：
- name: 变换节点的可选名称
- position: 可选 [x, y] 节点位置坐标
- rotation: 旋转角度
- scale: 统一缩放因子
- center: 可选 [x, y] 转换中心
"""
try:
logger.info(f"调用工具：create_transform")
nuke = get_nuke_connection()
# 准备变换节点的参数
parameters = {
"rotate": rotation,
"scale": scale
}
if center:
parameters["center"] = center
# 调用通用 create_node 命令
result = nuke.send_command("create_node", {
"node_type": "Transform",
"name": name,
"position": position,
"parameters": parameters
})
actual_name = result.get("name", "unknown")
return f"创建名为 '{actual_name}' 的变换节点，旋转={rotation}°，缩放={scale}"
except Exception as e:
logger.error(f"错误在 create_transform：{str(e)}")
return f"创建变换节点失败：{str(e)}"
这种模式允许您构建提供高级功能的专用工具，同时利用现有的命令基础设施。
故障排除
连接问题
如果 Claude 无法连接到 Nuke，请检查以下内容：
- Nuke 正在运行：确保 Nuke 已打开并正在运行
- 插件处于活动状态：验证 NukeMCP 面板显示“在端口 9876 上运行”
- 端口配置：确保端口在 Nuke 和 MCP 服务器中匹配
- 防火墙设置：检查您的防火墙是否阻止了连接
常见错误
- “无法连接到 Nuke”：确保 Nuke 插件正在运行并且使用正确的端口
- “等待响应时套接字超时”：Nuke 中的操作可能花费时间过长
- “创建节点失败”：检查节点类型名称是否正确
开发
这是初始实现。未来改进可能包括：
- 支持更多专门的 Nuke 功能（如 Roto、跟踪等）
- 更好的错误处理和超时管理
- 支持模板化工作流程
- 与其他资产管理系统的集成