Cursor에서 KwaFlux 쓰는 법: MCP 설정, 첫 요청, 문제 해결

핵심 요약

• Cursor 에이전트는 KwaFlux에 들어 있는 로컬 MCP 서버를 통해 KwaFlux를 움직일 수 있습니다. 설정은 KwaFlux에서 버튼 하나를 누르거나 mcp.json에 항목 하나를 넣으면 됩니다.
• KwaFlux를 열어 두고 Node.js를 설치해 두세요. 서버는 내 컴퓨터에서 돌아가는 로컬 프로그램이라 Cursor의 클라우드 에이전트는 접근할 수 없습니다.
• Cursor는 기본적으로 MCP 도구를 실행하기 전에 묻습니다. 먼저 읽기 전용 도구를 승인해 연결을 확인하세요.
• 설정 실패는 대부분 세 가지 때문입니다. JSON에서 Windows 경로의 백슬래시를 이스케이프하지 않았거나, 엉뚱한 mcp.json을 고쳤거나, 다시 불러오지 않은 경우입니다.

Cursor 에이전트는 KwaFlux와 함께 설치되는 로컬 MCP 서버를 통해 내 컴퓨터의 KwaFlux를 움직일 수 있습니다. KwaFlux에서 설정 › Agent(MCP)를 열고 Cursor를 고른 다음 Cursor에 설치를 클릭하거나, Cursor의 mcp.json에 항목 하나를 붙여 넣으면 됩니다. 그다음 에이전트에게 영상 진단, 복구, 변환, 화질 향상을 요청하세요.

설정은 5분 정도 걸립니다. 서버는 Cursor가 실행하고, 처리는 KwaFlux가 맡습니다.

이 글에서는 Cursor에 KwaFlux를 추가하는 두 가지 방법, 연결 확인 방법, 처음에 무엇을 요청할지, 그리고 흔한 문제를 해결하는 방법을 알아봅니다.

목차

1. Cursor는 MCP 서버로 무엇을 하나요?
2. 시작하기 전에
3. 방법 1. KwaFlux에서 버튼 하나로 설치하기
4. 방법 2. mcp.json 직접 편집하기
5. 연결 확인하기
6. 첫 요청 해 보기
7. 승인과 자동 실행
8. 문제 해결
9. 자주 묻는 질문

Cursor는 MCP 서버로 무엇을 하나요?

MCP 서버는 Cursor 에이전트에게 도구를 더해 줍니다. 로컬(stdio) 서버라면 Cursor가 시작될 때 내 컴퓨터에서 그 프로그램을 실행하고, 요청에 필요할 때 에이전트가 도구를 호출합니다.

KwaFlux 서버는 앱과 함께 제공되는 Node.js 스크립트입니다. 이 서버의 도구로 앱 상태를 확인하고, 변환, 복구, 화질 향상 같은 작업을 대기열에 넣고, 작업이 끝날 때까지 기다립니다. 에이전트가 무엇이고 이 루프가 어떻게 돌아가는지는 AI 에이전트란?을 참고하세요.

시작하기 전에

참고: Mac에서는 KwaFlux 코드 조각이 스크립트 경로 대신 앱 안의 헬퍼(<KwaFlux.app>/Contents/Helpers/kwaflux-mcp-run)를 가리킵니다. 실제 위치가 채워지도록 앱에서 복사하세요.

방법 1. KwaFlux에서 버튼 하나로 설치하기

1. KwaFlux에서 설정을 열고 Agent(MCP)로 이동합니다.
2. MCP 호스트에서 Cursor를 고릅니다.
3. Cursor에 설치를 클릭합니다. KwaFlux가 구성을 복사하고 설치 링크로 Cursor를 엽니다.
4. Cursor에서 설치를 승인합니다.
5. KwaFlux 안내 문구대로 "설치 후 Cursor에서 MCP를 다시 로드하세요."

클릭하면 KwaFlux가 구성을 복사한 뒤 "설정을 복사하고 Cursor를 실행했습니다. 열리지 않으면 직접 붙여넣으세요"라는 메시지를 띄웁니다. Cursor가 열리지 않으면 방법 2로 진행하세요. 구성은 이미 클립보드에 있습니다.

이 버튼은 아래와 같은 형식의 링크를 엽니다. 구성은 링크 끝에 인코딩되어 들어 있습니다.

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

Windows에 기본 경로로 설치했을 때의 링크입니다. KwaFlux를 다른 곳에 설치했다면 링크가 다를 수 있습니다.

방법 2. mcp.json 직접 편집하기

Cursor는 두 파일에서 MCP 서버를 읽습니다.

KwaFlux는 프로젝트의 일부가 아니라 데스크톱 앱이므로 전역 파일을 쓰세요.

1. KwaFlux의 MCP 호스트에서 Cursor를 고르고 구성 복사를 클릭합니다.
2. ~/.cursor/mcp.json을 열거나 새로 만듭니다.
3. 새 파일이라면 코드 조각 전체를 붙여 넣습니다. 이미 다른 서버가 있다면 기존 mcpServers 안에 kwaflux 항목만 추가합니다.

Windows 기본 설치라면 코드 조각은 다음과 같습니다.

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

4. 저장한 뒤 Cursor를 재시작하거나 Customize(사용자 지정)에서 서버를 껐다가 다시 켭니다.

팁: 백슬래시는 두 개 그대로 두세요. JSON에서 \ 하나는 이스케이프 시퀀스의 시작이라, C:\Program Files라고 쓰면 파일 전체가 유효하지 않게 되고 Cursor는 KwaFlux뿐 아니라 그 파일에 있는 모든 서버를 불러오지 않습니다.

연결 확인하기

1. Cursor 사이드바에서 Customize를 열고 kwaflux를 찾습니다. 활성화되어 있고 도구 목록이 보여야 합니다.
2. 에이전트 채팅에서 이렇게 물어봅니다.

KwaFlux가 실행 중인가요? KwaFlux 도구로 확인해 주세요.

에이전트가 kwaflux_get_app_status를 호출합니다. KwaFlux가 열려 있으면 로그인 여부가 답에 포함됩니다. 닫혀 있으면 도구가 app_not_running으로 시작하는 오류를 돌려줍니다. KwaFlux를 연 다음 다시 물어보세요.

3. 작업 목록을 요청해 봅니다. 목록이 비어 있어도 괜찮습니다. 전체 연결이 제대로 작동한다는 뜻입니다.

첫 요청 해 보기

로컬 전체 경로를 알려 주고, 결과물을 어디에 쓸지 말해 주세요.

모든 작업은 KwaFlux 작업 목록에 나타나므로 거기서 진행 상황을 보거나 일시 중지, 취소할 수 있습니다. 변환에 대한 자세한 내용은 변환기를 참고하세요.

프레임 보간과 매팅, 교체 도구는 앱에 남아 있으며, 이런 요청이 오면 어시스턴트는 사용자를 앱으로 안내하라는 응답을 받습니다. 에이전트 다운로드는 에이전트 권한의 에이전트의 다운로드 허용을 매번 확인으로 바꾸지 않는 한 꺼져 있습니다. 이렇게 설정하면 KwaFlux가 다운로드마다 팝업을 띄우고, 어시스턴트도 그 콘텐츠를 내려받을 권리가 있는지 채팅에서 확인을 요청합니다.

승인과 자동 실행

Cursor 문서에 따르면 Cursor는 "기본적으로 MCP 도구를 사용하기 전에 승인을 요청"하며, MCP 도구에도 터미널 명령과 같은 Run Modes가 적용됩니다. KwaFlux에 쓰기에도 합리적인 기본값입니다.

• 앱 상태, 작업 목록, 작업 세부 정보, 내보내기 포맷 목록 같은 읽기 전용 도구는 허용 목록에 넣어도 무리가 없습니다.
• 작업을 대기열에 넣는 도구는 원본 옆에 새 파일을 만듭니다. 내 요청이 믿을 만해질 때까지는 직접 승인하세요.

문제 해결

Cursor에만 해당하지 않는 문제는 KwaFlux MCP 문제 해결 가이드를 참고하세요.

마치며

Cursor에 설치를 클릭하거나 ~/.cursor/mcp.json에 항목 하나를 붙여 넣으세요. 그런 다음 다시 불러오고, KwaFlux를 열어 둔 채 첫 실제 작업 전에 에이전트에게 앱 상태부터 확인하게 하세요. 그 뒤로는 변환, 복구, 화질 향상을 Cursor 채팅에서 시작할 수 있고, 그 작업은 KwaFlux 작업 목록에 나타납니다.

Cursor로 KwaFlux를 움직여 보세요

KwaFlux에는 Cursor를 비롯한 MCP 앱에서 쓸 수 있는 로컬 MCP 서버가 들어 있습니다. AI 처리는 사용자 GPU에서 실행되며 미디어 파일이 처리를 위해 업로드되지 않습니다. Windows 10(64비트, 버전 1809 이상), Windows 11, Apple Silicon 탑재 macOS 12 이상에서 실행됩니다. 파일 가져오기와 앱 둘러보기에는 계정이 필요 없습니다. 내보내기, 변환, 파일 복구, 링크에서 파일 다운로드에만 로그인과 유료 플랜이 필요합니다.

KwaFlux 받기 · 플랜 보기