在 Claude Code 和 Claude Desktop 里驱动 KwaFlux（MCP 配置）

要点速览

• Claude Code 用 KwaFlux 生成的一条 claude mcp add 命令就能接入；Claude Desktop 则是在 claude_desktop_config.json 里加一项。
• Claude Code 请用用户级作用域，这样 KwaFlux 在每个项目里都能用，而不只是某一个文件夹。
• 改完 Claude Desktop 的配置后，要连同系统托盘里的图标一起真正退出，否则它不会加载新服务。
• 两个客户端在运行 MCP 工具前都会征求同意；在 Claude Code 里用 /mcp 可以看到 KwaFlux 是否连上、提供了几个工具。

Claude 可以通过随 KwaFlux 一起安装的本地 MCP 服务，在你的电脑上操作 KwaFlux。对 Claude Code，KwaFlux 会给你一条现成的 claude mcp add 命令；对 Claude Desktop，它会给你一段 JSON，合并进 claude_desktop_config.json 就行。不管用哪个，Claude 干活时都要保持 KwaFlux 开着。

本文会讲两个 Claude 客户端各自怎么接入、配置存在哪儿、怎么确认连通、先问什么，以及常见问题怎么解决。

目录

1. 用 Claude Code 还是 Claude Desktop？
2. 开始之前
3. Claude Code：一条命令
4. Claude Code：和项目共享
5. Claude Desktop：编辑配置文件
6. 第一批指令
7. 长任务与超时
8. 问题排查
9. 常见问题

用 Claude Code 还是 Claude Desktop？

Claude Code 是 Anthropic 面向终端和 IDE 的编程 Agent；Claude Desktop 是 Windows 和 macOS 上的 Claude 聊天应用。两者都能运行本地 MCP 服务，也都能用 KwaFlux。

如果你主要想和 Claude 聊聊自己的视频，从 Claude Desktop 入手更简单；如果你本来就在终端或 IDE 里干活，Claude Code 能直接融进去。其他助手见我们的对比。

开始之前

• KwaFlux 1.0.14 或更新版本，并且开着。 MCP 服务要和正在运行的应用对话。
• Node.js 18 或更新版本，且在 PATH 中。 KwaFlux 设置卡片上写着：“宿主通过 Node.js 18 或更高版本启动该服务，请确认已安装 Node 且在 PATH 中。”如果 node --version 报错，去 nodejs.org 装当前的 LTS 版本。KwaFlux 设置卡片也会查找 Node.js，并把它的完整路径写进配置，下面的示例就是这样；如果找不到，卡片会提示你，并改写成 node。
• 在 KwaFlux 里： 打开 设置 › Agent（MCP），在 MCP 宿主 里选 Claude，再选 Claude Code 或 Claude Desktop。

Claude Code：一条命令

1. 选中 Claude Code，点 复制安装命令。
2. 粘到终端里运行。Windows 默认安装位置对应的命令是：

claude mcp add --scope user kwaflux -- "C:\Program Files\nodejs\node.exe" "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

3. 新开一个 Claude Code 会话，运行 /mcp。你应该能看到 kwaflux 已连接，后面写着工具数量。

命令里有两处要留意：

• **--scope user** 把服务存进 ~/.claude.json，所有项目都能用。Claude Code 默认的本地作用域，只会让 KwaFlux 出现在你运行命令的那个文件夹里。
• **--** 用来隔开 Claude 自己的选项和启动服务的命令。Claude Code 的文档说明：“-- 之后的所有内容都会原样传给服务。”

Claude Code：和项目共享

KwaFlux 的提示也给了项目文件的写法：“写入项目根 .mcp.json，或执行下方 CLI。”项目里的 .mcp.json 用来通过版本控制，把服务分享给在这个文件夹里干活的所有人。如果一个团队把视频项目放在代码仓库里，而且每个人都把 KwaFlux 装在同一位置，就可以用它。

选中 Claude Code，点 复制配置，存为项目根目录下的 .mcp.json：

{
  "mcpServers": {
    "kwaflux": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": [
        "C:\\Program Files\\KwaFlux\\Tools\\kwaflux-mcp\\kwaflux_mcp.mjs"
      ]
    }
  }
}

在交互式会话里，Claude Code 使用项目 .mcp.json 中的服务之前会先请你批准。批准之前，/mcp 里这个服务会显示为待批准。

Claude Desktop：编辑配置文件

1. 在 KwaFlux 里选 Claude › Claude Desktop，点 复制配置。
2. 在 Claude Desktop 里，从 Claude 菜单打开 Settings，进入 Developer，点 Edit Config。它会打开（或新建）： - Windows 上：%APPDATA%\Claude\claude_desktop_config.json - macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
3. 把 kwaflux 这一项合并进 mcpServers，别删掉已有的服务。
4. 真正退出 Claude Desktop，包括系统托盘或菜单栏里的图标，然后重新打开。KwaFlux 的提示在这一点上说得很直接：改完必须真正退出再开。
5. 在对话里打开输入框左下角的菜单，进入 Connectors，确认 kwaflux 及其工具都在列表里。

除非你在某段对话里放行了某个工具，否则 Claude Desktop 在每个工具运行前都会征求你的同意。

第一批指令

先做一次只读检查：

用 KwaFlux 的工具查一下 KwaFlux 开着没有、我登录了没有。

然后试试真正的任务，记得带完整的本机路径：

智能补帧，以及抠像和替换类工具，仍要在应用里做，助手会被告知把你引导过去。AI 发起下载默认关闭，要在 Agent 授权 里把 允许 Agent 发起下载 设为 每次确认。之后每次下载 KwaFlux 都会弹窗问你，助手也会在对话里请你确认有权下载那些内容。

技巧： 在 Claude Code 里，KwaFlux 的工具名是 mcp__kwaflux__<工具名>，比如 mcp__kwaflux__kwaflux_get_app_status。在权限规则里用这些名字放行只读工具，Claude 每次查任务列表就不用再问你了。

长任务与超时

视频任务动辄几分钟。KwaFlux 的等待工具每次最多等 300 秒，默认 60 秒，然后报告任务是否完成；没完成，Claude 再等一次就行。

如果机器较慢、服务本身启动也慢，Claude Code 文档里介绍了控制启动超时的环境变量 MCP_TIMEOUT，比如 MCP_TIMEOUT=10000 claude。至于工具调用，可以在项目 .mcp.json 的条目里加一个以毫秒为单位的 timeout 字段；如果你会让它长时间等待，就设到 300,000 以上。

问题排查

所有宿主共有的问题，见 KwaFlux MCP 排障指南。

结语

在 Claude Code 里，运行 KwaFlux 帮你复制好的那条命令（用户级作用域），再看看 /mcp。在 Claude Desktop 里，把那一项合并进 claude_desktop_config.json，真正退出后重开。然后保持 KwaFlux 开着，先做一次状态检查。

在 Claude 里驱动 KwaFlux

KwaFlux 自带本地 MCP 服务，支持 Claude Code、Claude Desktop 等 MCP 应用。AI 处理在你自己的 GPU 上运行，媒体文件不会为了处理而上传。可在 Windows 10（64 位，1809 或更新版本）、Windows 11，以及搭载 Apple Silicon 的 macOS 12 或更新版本上运行。导入文件和浏览应用都不需要账号。仅在导出、转换、文件修复和从链接下载文件时需要登录并购买付费方案。

下载 KwaFlux · 查看方案