nuke_mcp | 通往MCP之路

Nuke-MCP

一个基于模型上下文协议（Model Context Protocol, MCP）的桥梁，连接 The Foundry 的 Nuke 与 AI 系统。

概述

Nuke-MCP 允许 AI 助手通过 socket 连接与 Nuke 进行交互，支持以下功能：

获取 Nuke 脚本信息

创建、修改和删除节点

在节点图中定位节点

连接节点

控制播放和渲染

在 Nuke 中执行任意 Python 代码

组件

Nuke 插件 (nuke_mcp_addon.py)：在 Nuke 内部创建 socket 服务器的脚本

MCP 服务器 (nuke_mcp_server.py)：连接 Nuke 插件并向 AI 系统暴露工具的 Python 服务器

入口脚本 (main.py)：用于启动 MCP 服务器的简单脚本

安装

前置条件

The Foundry 的 Nuke（任何近期版本均可）

Python 3.7+

FastMCP 包

安装 FastMCP 包

安装 Nuke-MCP

克隆或下载此仓库

将 nuke_mcp_addon.py 复制到 Nuke 脚本文件夹或 Nuke Python 路径中的某个位置

使用

安装 Nuke 插件

复制插件文件：

将 nuke_mcp_addon.py 文件放置到 Nuke 可以找到的位置：

复制到 Nuke 脚本文件夹（通常位于 ~/.nuke（Linux/Mac）或用户主目录（Windows））
或者放置到 Nuke Python 路径中的某个文件夹

创建启动脚本（推荐）：

在 .nuke 目录中创建或编辑现有的 init.py 文件

添加以下行以在 Nuke 启动时自动加载插件：

手动加载（替代方案）：

如果不想自动加载，可以每次手动加载：

打开 Nuke
进入 Script Editor 面板
运行 import nuke_mcp_addon

停靠 NukeMCP 面板

默认情况下，NukeMCP 面板以浮动窗口形式打开。如果希望将其停靠在 Nuke 界面中，可以修改 nuke_mcp_addon.py 中的 NukeMCPPanel 类：

你还可以修改面板在菜单中的显示方式。根据你的 menu.py 文件，你可以添加以下内容：

确保此行在 menu.py 文件中未被注释，以确保其与现有工具栏结构正确集成。

故障排除

要在 Claude Desktop 中使用 Nuke-MCP，请按照以下步骤操作：

下载并安装 Claude Desktop：

从 Anthropic 官网下载 Claude Desktop

安装并设置你的账户

启用开发者模式：

打开 Claude Desktop

进入设置

启用开发者模式（可能需要特定权限）

编辑配置文件：

在 Claude Desktop 设置中，点击“编辑配置”（或直接编辑 claude_desktop_config.json 文件）

添加 Nuke-MCP 服务器配置：

替换路径：

更新路径为 main.py 文件的实际保存路径

确保使用完整绝对路径

对于 Windows，使用正斜杠或转义反斜杠：

或

注意："trusted": true 标志是完整功能所必需的

重启 Claude Desktop：

保存配置文件

重启 Claude Desktop 以应用更改

现在，当你使用 Claude Desktop 时，可以通过 MCP 连接指示其与 Nuke 交互。

系统架构

系统由三个主要组件协同工作：

Nuke 插件：在 Nuke 内部运行，创建监听命令的 socket 服务器

MCP 服务器：作为 AI 系统与 Nuke 之间的中间件

AI 客户端：连接 MCP 服务器以控制 Nuke（例如 Claude Desktop）

可用工具

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)：控制 Viewer 播放

execute_nuke_code(code)：在 Nuke 中运行 Python 代码

auto_layout_nodes(selected_only)：自动排列节点

set_frames(first_frame, last_frame, current_frame)：设置帧范围

create_viewer(input_node)：创建 Viewer 节点

示例

创建简单模糊节点

构建 Grade 节点链

渲染输出

给 Claude 的示例命令

与 Claude Desktop 配合使用时，可以通过自然语言指令控制 Nuke。以下是一些示例命令：

基本脚本分析

创建完整合成设置

构建绿屏抠像设置

添加特效

增强现有脚本

3D 场景设置

扩展 MCP 工具

你可以通过向 nuke_mcp_server.py 文件添加新工具来扩展系统。MCP 工具使用 @mcp.tool() 装饰器模式定义。

工具结构

每个工具都遵循以下基本结构：

添加新工具

添加新工具的步骤如下：

确定功能：明确要添加的功能

在 Nuke 插件中添加新方法（在 nuke_mcp_addon.py 中）：

在 NukeMCPServer 类中添加方法

在 execute_command 方法中的 handlers 字典中添加条目

在 nuke_mcp_server.py 中创建对应的工具：

使用 @mcp.tool() 装饰器

定义带类型提示的参数

添加描述性文档字符串

实现调用相应 Nuke 命令的逻辑

彻底测试新工具

示例：添加 Transform 节点工具

以下是如何添加一个用于创建 Transform 节点的专用工具的示例：

此模式允许你构建提供更高级功能的专用工具，同时利用现有的命令基础设施。

故障排除

连接问题

如果 Claude 无法连接到 Nuke，请检查以下内容：

Nuke 正在运行：确保 Nuke 已打开并运行

插件已激活：验证 NukeMCP 面板显示“Running on port 9876”

端口配置：确保 Nuke 和 MCP 服务器中的端口匹配

防火墙设置：检查防火墙是否阻止了连接

常见错误

"无法连接到 Nuke"：确保 Nuke 插件正在运行并使用正确的端口

"等待响应时 socket 超时"：Nuke 中的操作可能耗时过长

"创建节点失败"：检查节点类型名称是否正确

开发

这是一个初始实现。未来的改进可能包括：

支持更多专用 Nuke 功能（Roto、Tracking 等）

更好的错误处理和超时管理

支持基于模板的工作流

与更多资产管理系统集成

许可证

MIT 许可证