Nuke-MCP 使用说明

Nuke-MCP 是一个 MCP 服务器实现，旨在作为 AI 助手（如支持 MCP 的大模型客户端）和行业标准的合成软件 The Foundry Nuke 之间的桥梁。它允许 AI 通过标准协议与 Nuke 交互，执行脚本、控制节点、管理渲染等任务。

项目简介

Nuke-MCP 由两个主要部分组成：

一个运行在 Nuke 内部的 Python 插件，提供与 Nuke 核心功能的socket接口。
一个独立的 Python MCP 服务器，连接到 Nuke 插件，并将 Nuke 功能封装为 MCP 工具和 Prompt 模板暴露给 AI 客户端。

该项目使得 AI 能够理解 Nuke 的上下文（脚本结构、节点参数）并对其进行操作，实现基于对话的流程控制和自动化。

主要功能点

获取场景信息: 查询当前 Nuke 脚本的全局设置和所有节点的信息。
节点操作: 创建、修改、删除、定位、连接 Nuke 中的各种节点。
流程控制: 控制 Viewer 的回放、设置全局帧范围。
渲染管理: 触发 Nuke 进行渲染，可指定帧范围和 Write 节点。
代码执行: 在 Nuke 环境中执行任意 Python 代码，提供高级控制能力。
自动布局: 自动整理节点图的布局，提高可读性。
工作流辅助: 提供针对 Nuke 合成最佳实践的建议和自动修正，帮助创建规范的节点图。

安装步骤

安装前置依赖:
- 确保已安装 The Foundry Nuke (任意近期版本)。
- 安装 Python 3.7 或更高版本。
安装 FastMCP 包: 打开终端或命令提示符，运行以下命令安装 MCP 服务器框架：
```
pip install fastmcp
```
安装 Nuke-MCP:
- 克隆或下载 Nuke-MCP 仓库到本地目录。
- 将仓库中的 'nuke_mcp_addon.py' 文件拷贝到 Nuke 的脚本文件夹（通常是 '~/.nuke' 目录，或添加到 Nuke 的 Python 路径中）。
在 Nuke 中启动插件:
- 推荐方式 (自动加载): 在 Nuke 的 '.nuke' 目录下创建或编辑 'init.py' 文件，添加以下行以在 Nuke 启动时自动加载插件：
```
import nuke_mcp_addon
```
- 手动方式: 打开 Nuke，在 Script Editor 中运行 'import nuke_mcp_addon'。
- 加载成功后，应能看到 Nuke MCP 面板显示服务器状态，通常会显示正在监听的端口号（默认为 9876）。确保插件在 Nuke 中正常运行并显示“Running”状态。

服务器配置 (供 MCP 客户端使用)

要让支持 MCP 的 AI 客户端（如 Claude Desktop）连接到 Nuke-MCP 服务器，需要在客户端的配置中添加服务器信息。这通常是一个 JSON 格式的配置项。以下是一个示例配置结构，你需要根据你的 Nuke-MCP 仓库实际路径进行修改：

{
  "mcpServers": {
    "nuke": {  // 服务器名称，AI 客户端将使用此名称引用
      "command": "python", // 启动服务器的命令
      "args": [  // 启动服务器的参数
        "/path/to/your/nuke-mcp/main.py" // 指向你本地 nuke-mcp 仓库中的 main.py 文件的绝对路径
      ],
      "trusted": true // 是否信任该服务器 (通常需要信任才能调用所有工具)
    }
  }
}

重要: 请务必将 '/path/to/your/nuke-mcp/main.py' 替换为你实际存放 'main.py' 文件的完整绝对路径。在 Windows 上，路径分隔符可以是正斜杠 '/' 或双反斜杠 '\'。

配置完成后，重启你的 AI 客户端。客户端会自动检测并连接到配置的 MCP 服务器（在 Nuke 插件运行的情况下）。

基本使用方法

一旦 Nuke 插件和 Nuke-MCP 服务器都已运行，并且 AI 客户端配置正确并连接成功，你就可以通过 AI 客户端与 Nuke 进行交互。

启动 Nuke 和 NukeMCP 插件: 确保 Nuke 运行，并且 'nuke_mcp_addon.py' 插件已加载并显示“Running”状态。
启动 Nuke-MCP 服务器: 通过命令行运行 'python /path/to/your/nuke-mcp/main.py' 来启动 MCP 服务器。
在 AI 客户端中交互: 在 AI 客户端的对话框中，直接使用自然语言描述你希望 Nuke 执行的任务。AI 客户端会识别你的意图，并调用对应的 Nuke-MCP 工具。

示例指令 (对 AI 客户端说):

“告诉我当前的 Nuke 脚本里有什么。” (对应 'get_script_info' 工具)
“创建一个 Blur 节点，并把它连接到 Read1 节点。” (对应 'create_node' 和 'connect_nodes' 工具)
“把 Grade1 节点的 gain 参数设置为 1.5。” (对应 'modify_node' 工具)
“渲染从第 101 帧到 200 帧，使用 Write_Final 节点。” (对应 'render' 工具)
“把节点图自动整理一下。” (对应 'auto_layout_nodes' 或 'organize_node_graph' 工具)
“创建一个绿屏抠像的工作流模板。” (对应 'create_workflow_template' 工具)

你也可以询问 AI 客户端 Nuke-MCP 的使用方法，它可能会使用 'nuke_mcp_usage' Prompt 模板来回答你。

关键词