Claude Code와 Claude Desktop에서 KwaFlux 쓰는 법(MCP 설정)

핵심 요약

• Claude Code는 KwaFlux가 만들어 주는 claude mcp add 명령 하나로, Claude Desktop은 claude_desktop_config.json에 항목 하나를 넣는 것으로 KwaFlux에 연결됩니다.
• Claude Code에서는 user 범위를 쓰세요. 그래야 폴더 하나가 아니라 모든 프로젝트에서 KwaFlux를 쓸 수 있습니다.
• Claude Desktop은 구성을 고친 뒤 시스템 트레이에 남은 아이콘까지 포함해 앱을 종료해야 합니다. 그러지 않으면 서버를 불러오지 않습니다.
• 두 클라이언트 모두 MCP 도구를 실행하기 전에 묻습니다. Claude Code에서는 /mcp로 KwaFlux가 연결됐는지, 도구가 몇 개인지 확인할 수 있습니다.

Claude는 KwaFlux와 함께 설치되는 로컬 MCP 서버를 통해 내 컴퓨터의 KwaFlux를 움직일 수 있습니다. Claude Code용으로는 KwaFlux가 바로 쓸 수 있는 claude mcp add 명령을 만들어 주고, Claude Desktop용으로는 claude_desktop_config.json에 병합할 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는 터미널과 IDE에서 쓰는 Anthropic의 코딩 에이전트이고, Claude Desktop은 Windows와 macOS용 Claude 채팅 앱입니다. 둘 다 로컬 MCP 서버를 실행할 수 있고, 둘 다 KwaFlux를 쓸 수 있습니다.

주로 영상에 대해 Claude와 대화하고 싶다면 Claude Desktop으로 시작하는 편이 간단합니다. 이미 터미널이나 IDE에서 일한다면 Claude Code가 그 흐름에 잘 맞습니다. 다른 어시스턴트는 호스트 비교 글을 참고하세요.

시작하기 전에

• KwaFlux 1.0.14 이상, 실행 중. MCP 서버는 실행 중인 앱과 통신합니다.
• PATH에 있는 Node.js 18 이상. KwaFlux 설정 카드에는 "호스트는 Node.js 18 이상으로 서버를 실행하므로 Node가 설치되어 PATH에 있어야 합니다."라고 나옵니다. node --version이 실패하면 nodejs.org에서 현재 LTS를 설치하세요. KwaFlux 설정 카드는 Node.js도 찾아서 아래 예시처럼 그 전체 경로를 구성에 적어 줍니다. 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의 기본값인 local 범위로 두면 명령을 실행한 폴더에서만 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 안내 문구도 편집한 뒤에는 Claude Desktop을 끝까지 종료하라고 분명히 적어 둡니다.
5. 대화 화면에서 입력창 왼쪽 아래의 메뉴를 열고 Connectors(커넥터)로 이동해 kwaflux가 도구와 함께 표시되는지 확인합니다.

Claude Desktop은 대화 단위로 도구를 허용하지 않는 한 도구를 실행할 때마다 먼저 승인을 요청합니다.

첫 요청 해 보기

읽기 전용 확인부터 해 보세요.

KwaFlux 도구로 KwaFlux가 실행 중인지, 내가 로그인되어 있는지 확인해 주세요.

그다음 로컬 전체 경로를 넣어 실제 작업을 시켜 봅니다.

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

팁: Claude Code에서 KwaFlux 도구는 mcp__kwaflux__kwaflux_get_app_status처럼 mcp__kwaflux__<tool> 형태의 이름으로 표시됩니다. 권한 규칙에 이 이름으로 읽기 전용 도구를 허용해 두면 Claude가 작업 목록을 확인할 때마다 승인 요청을 받지 않아도 됩니다.

긴 작업과 타임아웃

영상 작업은 몇 분씩 걸릴 수 있습니다. KwaFlux의 대기 도구는 호출 한 번에 최대 300초(기본 60초)까지 기다린 뒤 작업이 끝났는지 알려 줍니다. 아직 끝나지 않았다면 Claude가 다시 기다리면 됩니다.

컴퓨터가 느려서 서버 자체가 늦게 시작된다면, Claude Code 문서에 나온 시작용 환경 변수 MCP_TIMEOUT을 쓸 수 있습니다. 예를 들면 MCP_TIMEOUT=10000 claude입니다. 도구 호출에는 프로젝트 .mcp.json 항목에 밀리초 단위의 timeout 필드를 넣을 수 있습니다. 긴 대기를 요청할 생각이라면 300,000보다 크게 설정하세요.

문제 해결

모든 호스트에 공통된 문제는 KwaFlux MCP 문제 해결 가이드를 참고하세요.

마치며

Claude Code에서는 KwaFlux가 복사해 주는 명령을 user 범위로 실행하고 /mcp로 확인하세요. Claude Desktop에서는 claude_desktop_config.json에 항목을 병합하고, 앱을 끝까지 종료한 다음 다시 여세요. 그런 다음 KwaFlux를 열어 두고 상태 확인부터 시작하면 됩니다.

Claude로 KwaFlux를 움직여 보세요

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

KwaFlux 받기 · 플랜 보기