How to Use KwaFlux from Cursor: MCP Setup, First Requests, and Fixes

Key takeaways

• Cursor's agent can drive KwaFlux through the local MCP server that ships with the app. Setup is one button in KwaFlux, or one entry in mcp.json.
• Keep KwaFlux open and Node.js installed. The server is a local program on your computer, so Cursor's cloud agents can't reach it.
• Cursor asks before running MCP tools by default. Approve the read-only ones first to check the connection.
• Most setup failures come from three things: an unescaped Windows path in JSON, editing the wrong mcp.json, and not reloading.

Cursor's agent can drive KwaFlux on your computer through the local MCP server that installs with the app. In KwaFlux, open Settings › Agent (MCP), choose Cursor, and click Install in Cursor, or paste one entry into Cursor's mcp.json. Then ask the agent to diagnose, repair, convert, or enhance a video.

The setup takes about five minutes. Cursor runs the server, and KwaFlux does the processing.

In this guide, you'll learn both ways to add KwaFlux to Cursor, how to check the connection, what to ask first, and how to fix the usual problems.

Contents

1. What does Cursor do with an MCP server?
2. Before you start
3. Method 1. Install from KwaFlux with one button
4. Method 2. Edit mcp.json yourself
5. Check that it's connected
6. Your first requests
7. Approvals and auto-run
8. Troubleshooting
9. FAQ

What does Cursor do with an MCP server?

An MCP server gives Cursor's agent extra tools. For a local (stdio) server, Cursor starts the program on your computer when it loads, and the agent calls its tools when a request needs them.

KwaFlux's server is a Node.js script that comes with the app. Its tools check the app's status, queue jobs such as conversion, repair, and enhancement, and wait for them to finish. For what an agent is and how this loop works, see what is an AI agent.

Before you start

Sidenote: On a Mac, KwaFlux's snippet points at a helper inside the app (<KwaFlux.app>/Contents/Helpers/kwaflux-mcp-run) instead of a script path. Copy it from the app, so the real location is filled in.

Method 1. Install from KwaFlux with one button

1. In KwaFlux, open Settings and go to Agent (MCP).
2. Under MCP host, choose Cursor.
3. Click Install in Cursor. KwaFlux copies the config and opens Cursor with an install link.
4. Approve the install in Cursor.
5. As the KwaFlux hint says: "After installing, reload MCP in Cursor."

When you click it, KwaFlux copies the config and shows "Config copied, opening Cursor — paste manually if it doesn't open." If Cursor doesn't open, use Method 2; the config is already on your clipboard.

The button opens a link of this form, with the config encoded at the end:

cursor://anysphere.cursor-deeplink/mcp/install?name=kwaflux&config=eyJjb21tYW5kIjoiQzpcXFByb2dyYW0gRmlsZXNcXG5vZGVqc1xcbm9kZS5leGUiLCJhcmdzIjpbIkM6XFxQcm9ncmFtIEZpbGVzXFxLd2FGbHV4XFxUb29sc1xca3dhZmx1eC1tY3BcXGt3YWZsdXhfbWNwLm1qcyJdfQ

That's the link for a default Windows install. Yours may differ if you installed KwaFlux somewhere else.

Method 2. Edit mcp.json yourself

Cursor reads MCP servers from two files:

KwaFlux is a desktop app, not part of a project, so use the global file.

1. In KwaFlux, choose Cursor under MCP host and click Copy config.
2. Open ~/.cursor/mcp.json, or create it.
3. If the file is new, paste the whole snippet. If it already has servers, add only the kwaflux entry inside the existing mcpServers.

For a default Windows install, the snippet is:

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

4. Save, then restart Cursor or toggle the server off and on under Customize.

Pro tip: Keep the double backslashes. In JSON, a single \ starts an escape sequence, so C:\Program Files makes the whole file invalid, and Cursor drops every server in it, not just KwaFlux.

Check that it's connected

1. Open Customize in Cursor's sidebar and find kwaflux. It should be enabled, with its tools listed.
2. In agent chat, ask:

Is KwaFlux running? Check with the KwaFlux tools.

The agent calls kwaflux_get_app_status. If KwaFlux is open, the answer includes whether you're signed in. If it's closed, the tool returns an error that starts with app_not_running. Open KwaFlux and ask again.

3. Ask for your task list. An empty list is fine; it means the whole chain works.

Your first requests

Give full local paths, and say what you want the result for:

Each task appears in KwaFlux's task list, so you can watch it, pause it, or cancel it there. For conversion details, see Converter.

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.

Approvals and auto-run

Cursor's documentation says it "asks for approval before using MCP tools by default," and MCP tools follow the same Run Modes as terminal commands. That's a sensible default for KwaFlux:

• Read-only tools, such as app status, task list, task details, and the export format list, are safe to allowlist.
• Tools that queue jobs write new files next to your source. Keep approving those yourself until you trust your requests.

Troubleshooting

For problems that aren't specific to Cursor, see the KwaFlux MCP troubleshooting guide.

Final thoughts

Click Install in Cursor, or paste one entry into ~/.cursor/mcp.json. Then reload, keep KwaFlux open, and ask the agent to check the app's status before your first real job. After that, conversions, repairs, and enhancements can start from Cursor's chat and show up in KwaFlux's task list.

Drive KwaFlux from Cursor

KwaFlux includes a local MCP server for Cursor 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