How to Use KwaFlux from Claude Code and Claude Desktop (MCP Setup)

Key takeaways

• Claude Code connects to KwaFlux with one claude mcp add command that KwaFlux generates for you; Claude Desktop connects with one entry in claude_desktop_config.json.
• Use user scope in Claude Code, so KwaFlux is available in every project, not just one folder.
• Fully quit Claude Desktop after editing its config, including from the system tray, or it won't load the server.
• Both clients ask before running MCP tools, and /mcp in Claude Code shows whether KwaFlux connected and how many tools it offers.

Claude can drive KwaFlux on your computer through the local MCP server that installs with the app. For Claude Code, KwaFlux gives you a ready-made claude mcp add command. For Claude Desktop, it gives you a JSON entry to merge into claude_desktop_config.json. Either way, keep KwaFlux open while Claude works.

In this guide, you'll learn how to connect each Claude client, where its config lives, how to check the connection, what to ask first, and how to fix the usual problems.

Contents

1. Claude Code or Claude Desktop?
2. Before you start
3. Claude Code: one command
4. Claude Code: share it with a project
5. Claude Desktop: edit the config
6. Your first requests
7. Long jobs and timeouts
8. Troubleshooting
9. FAQ

Claude Code or Claude Desktop?

Claude Code is Anthropic's coding agent for the terminal and IDEs; Claude Desktop is the Claude chat app for Windows and macOS. Both can run local MCP servers, and both can use KwaFlux.

If you mostly want to talk to Claude about your videos, Claude Desktop is the simpler start. If you already work in a terminal or IDE, Claude Code fits in there. For the other assistants, see our comparison.

Before you start

• KwaFlux 1.0.14 or later, open. The MCP server talks to the running app.
• Node.js 18 or newer, on PATH. KwaFlux's Settings card says: "The host starts the server through Node.js 18 or newer, so Node must be installed and on PATH." Install the current LTS from nodejs.org if node --version fails. KwaFlux's Settings card also looks for Node.js and writes its full path into the config, as in the examples below; if it can't find Node.js, it says so and writes node instead.
• In KwaFlux: open Settings › Agent (MCP), choose Claude under MCP host, then pick Claude Code or Claude Desktop.

Claude Code: one command

1. With Claude Code selected, click Copy install command.
2. Paste it into a terminal and run it. For a default Windows install, it's:

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

3. Start a new Claude Code session and run /mcp. You should see kwaflux connected, with its tool count.

Two parts of that command matter:

• **--scope user** stores the server in ~/.claude.json for all your projects. Claude Code's default, local scope, would make KwaFlux appear only in the folder where you ran the command.
• **--** separates Claude's own options from the command that starts the server. Claude Code's docs explain that "Everything after -- is passed to the server untouched."

Claude Code: share it with a project

KwaFlux's hint also offers a project file: "Add to the project-root .mcp.json, or run the CLI." A project .mcp.json is for sharing servers with everyone who works in that folder, through version control. Use it if a team keeps a video project in a repository and everyone has KwaFlux installed in the same place.

With Claude Code selected, click Copy config and save it as .mcp.json in the project root:

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

Claude Code asks for approval before it uses servers from a project's .mcp.json in an interactive session. Until you approve, /mcp shows the server as pending.

Claude Desktop: edit the config

1. In KwaFlux, choose Claude › Claude Desktop and click Copy config.
2. In Claude Desktop, open Settings from the Claude menu, go to Developer, and click Edit Config. This opens, or creates: - Windows: %APPDATA%\Claude\claude_desktop_config.json - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Merge the kwaflux entry into mcpServers. Don't delete servers that are already there.
4. Fully quit Claude Desktop, including the icon in the system tray or menu bar, and open it again. KwaFlux's hint is blunt about this: "Fully quit Claude Desktop after editing."
5. In a conversation, open the menu at the bottom left of the input box, go to Connectors, and check that kwaflux is listed with its tools.

Claude Desktop asks for your approval before each tool runs, unless you allow a tool for the conversation.

Your first requests

Start with a read-only check:

Use the KwaFlux tools to check whether KwaFlux is running and I'm signed in.

Then try real jobs, with full local paths:

Frame interpolation and the matting and replace tools stay in the app; the assistant is told to send you there for those. Agent downloads stay off unless you set Let agents start downloads under Agent access to Ask every time. KwaFlux then shows a popup for each download, and the assistant also asks you to confirm in the chat that you have the right to download that content.

Pro tip: In Claude Code, KwaFlux's tools appear as mcp__kwaflux__<tool>, for example mcp__kwaflux__kwaflux_get_app_status. Use those names to allow the read-only tools in your permission rules, so you aren't asked every time Claude checks the task list.

Long jobs and timeouts

Video jobs can take minutes. KwaFlux's wait tool waits up to 300 seconds per call, 60 by default, and then reports whether the task is done. If it isn't, Claude can simply wait again.

If a slow machine makes the server itself start slowly, Claude Code's docs describe the MCP_TIMEOUT environment variable for startup, for example MCP_TIMEOUT=10000 claude. For tool calls, a project .mcp.json entry can take a timeout field in milliseconds. Set it above 300,000 if you ask for long waits.

Troubleshooting

For problems common to every host, see the KwaFlux MCP troubleshooting guide.

Final thoughts

In Claude Code, run the command KwaFlux copies for you, with user scope, and check /mcp. In Claude Desktop, merge the entry into claude_desktop_config.json and quit the app fully before reopening. Then keep KwaFlux open and start with a status check.

Drive KwaFlux from Claude

KwaFlux includes a local MCP server for Claude Code, Claude Desktop, and other MCP apps. AI processing runs locally on your GPU — media files are not uploaded for processing. It runs on Windows 10 (64-bit, version 1809 or later), Windows 11, and macOS 12 or newer on Apple Silicon. Importing files and exploring the app need no account. Signing in with an active paid plan is required only to export, convert, repair a file, or download a file from a link.

Download KwaFlux · See plans