윈도우 Claude Desktop MCP 설치 가이드 — 경로 오류·npx 문제 완전 해결

윈도우 환경에서 Claude Desktop에 MCP 서버를 연결하려다 경로 오류나 npx 실행 실패로 막히는 분들이 많습니다. 핵심은 세 가지입니다. 설정 파일은 %APPDATA%\Claude\claude_desktop_config.json에 있고, JSON 내 윈도우 경로는 백슬래시를 이중으로 써야 하며, npx가 PATH에서 인식되지 않을 때는 절대 경로를 직접 지정하면 됩니다. 이 가이드를 따라 하면 윈도우 환경의 대부분 MCP 설치 문제를 해결할 수 있습니다.

왜 윈도우에서 MCP 설치가 까다로운가

Mac과 달리 윈도우에는 경로 처리 방식에서 두 가지 장벽이 있습니다.

첫째, 백슬래시 이스케이프 문제. JSON 파일 안에서 백슬래시(\)는 이스케이프 문자로 해석됩니다. C:\Users\lee 같은 경로를 그대로 쓰면 파싱 오류가 납니다. 반드시 C:\\Users\\lee처럼 이중으로 써야 합니다.

둘째, npx PATH 미인식 문제. Claude Desktop은 일반 앱과 달리 시스템 환경 변수 PATH를 완전히 물려받지 않는 경우가 있습니다. 터미널에서는 npx가 잘 되는데 Claude Desktop에서만 “실행 파일을 찾을 수 없다”는 오류가 뜨는 이유가 바로 이 때문입니다.

두 문제를 모두 해결하는 방법을 단계별로 알아보겠습니다.

사전 준비

아래 항목을 먼저 확인하세요.

항목	확인 방법
Node.js 18 이상	PowerShell에서 node --version
npm / npx	PowerShell에서 npx --version
Claude Desktop 최신 버전	Claude Desktop 앱 내 업데이트 확인

Node.js가 설치되지 않았다면 nodejs.org에서 LTS 버전을 설치하세요. 설치 시 “Add to PATH” 옵션을 반드시 체크해야 합니다.

단계별 설치 방법

1단계 — npx 절대 경로 확인

먼저 PowerShell을 열어 npx의 실제 경로를 확인합니다.

where npx

출력 예시:

C:\Users\사용자명\AppData\Roaming\npm\npx.cmd

이 경로를 메모해 두세요. 나중에 Claude Desktop 설정 파일의 command 값에 씁니다.

2단계 — 설정 파일 위치 열기

파일 탐색기 주소창에 아래를 입력하거나 Enter를 누릅니다.

%APPDATA%\Claude

이 폴더 안에 claude_desktop_config.json 파일이 있어야 합니다. 파일이 없으면 Claude Desktop을 먼저 한 번 실행했다가 종료하면 자동으로 생성됩니다. 그래도 없다면 직접 생성하세요.

메모장으로 파일을 열려면 PowerShell에서 아래 명령을 실행합니다.

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

3단계 — JSON 설정 작성 (백슬래시 이중 사용)

아래는 npx 기반 MCP 서버를 추가하는 기본 설정 형태입니다.

{
  "mcpServers": {
    "서버이름": {
      "command": "C:\\Users\\사용자명\\AppData\\Roaming\\npm\\npx.cmd",
      "args": ["-y", "패키지명"]
    }
  }
}

중요: command 경로의 모든 \는 \\로 써야 합니다. 그렇지 않으면 Claude Desktop이 JSON을 읽지 못합니다.

npx 절대 경로 사용이 번거롭다면 슬래시(/)로 대체할 수도 있습니다.

{
  "mcpServers": {
    "서버이름": {
      "command": "C:/Users/사용자명/AppData/Roaming/npm/npx.cmd",
      "args": ["-y", "패키지명"]
    }
  }
}

여러 서버를 한 번에 추가할 때는 쉼표로 구분합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "C:\\Users\\사용자명\\AppData\\Roaming\\npm\\npx.cmd",
      "args": ["-y", "kordoc", "setup"]
    },
    "hwp-mcp": {
      "command": "C:\\Users\\사용자명\\AppData\\Roaming\\npm\\npx.cmd",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

4단계 — Claude Desktop 완전 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료해야 합니다. 창을 닫는 것만으로는 부족합니다. 윈도우 작업 표시줄 오른쪽 하단(시스템 트레이)에서 Claude 아이콘을 우클릭해 “종료”를 선택한 뒤 다시 실행하세요.

재시작 후 Claude 채팅창 하단에 MCP 도구 아이콘(망치 모양 또는 플러그 모양)이 표시되면 연결 성공입니다.

5단계 — 오류 로그 확인

도구 아이콘이 표시되지 않거나 오류가 나면 로그를 확인합니다.

%APPDATA%\Claude\logs

이 폴더 안에 날짜별 로그 파일이 있습니다. 최신 파일을 메모장으로 열어 아래 키워드를 검색하세요.

키워드	의미 및 해결법
ENOENT	지정한 경로의 파일이 없음. command 경로 재확인
spawn error	실행 파일 실행 실패. npx 절대 경로 사용
JSON parse error	JSON 문법 오류. 백슬래시·쉼표·괄호 확인
Cannot find module	npm 패키지 미설치 또는 패키지명 오타
timeout	서버가 응답 없음. 네트워크 또는 방화벽 확인

실제 설치 예시 — 한국산 MCP 서버 3종

아래는 윈도우에서 자주 사용하는 한국산 MCP 서버 설치 예시입니다. 스펙에 명시된 설치 명령을 그대로 사용했습니다.

코르독 (KorDoc)

HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환합니다. (서버 상세 보기)

"kordoc": {
  "command": "C:\\Users\\사용자명\\AppData\\Roaming\\npm\\npx.cmd",
  "args": ["-y", "kordoc", "setup"]
}

GitHub: github.com/chrisryugj/kordoc

HWP-MCP (한글 문서 MCP 서버)

AI가 한글(.hwp/.hwpx) 문서를 읽고 편집·생성할 수 있게 해줍니다. (서버 상세 보기)

"hwp-mcp": {
  "command": "C:\\Users\\사용자명\\AppData\\Roaming\\npm\\npx.cmd",
  "args": ["-y", "hwp-mcp"]
}

GitHub: github.com/treesoop/hwp-mcp

한포지 (HwpForge)

HWPX 문서를 AI 에이전트가 읽고 쓰고 변환합니다. 한컴 한글 HWPX(KS X 6101) 표준을 지원합니다. (서버 상세 보기)

"hwpforge": {
  "command": "C:\\Users\\사용자명\\AppData\\Roaming\\npm\\npx.cmd",
  "args": ["-y", "@hwpforge/mcp"]
}

GitHub: github.com/ai-screams/HwpForge

설정 데이터 흐름 구조

Claude Desktop (Windows)
    │
    ├─ 읽기: %APPDATA%\Claude\claude_desktop_config.json
    │
    ├─ 실행: npx.cmd (절대 경로)
    │        └─ MCP 서버 패키지 (Node.js)
    │
    └─ 통신: stdio (표준입출력)
             └─ Claude AI ↔ MCP 도구

Claude Desktop은 설정 파일을 읽어 각 MCP 서버를 자식 프로세스로 실행하고, stdio(표준입출력)를 통해 AI와 서버가 주고받는 구조입니다.

흔한 오류와 해결 방법 총정리

JSON 문법 오류

가장 흔한 실수입니다. 설정 파일을 저장하기 전에 JSON 유효성 검사기(jsonlint.com)에 붙여 넣어 확인하세요. 쉼표 하나만 빠져도 Claude Desktop이 설정을 읽지 못합니다.

PATH 문제 — “command not found”

앞서 설명한 대로 npx 절대 경로를 사용합니다. 또는 아래처럼 환경 변수를 설정에 추가하는 방법도 있습니다.

"서버이름": {
  "command": "npx",
  "args": ["-y", "패키지명"],
  "env": {
    "PATH": "C:\\Users\\사용자명\\AppData\\Roaming\\npm;C:\\Program Files\\nodejs"
  }
}

단, 이 방법은 기존 PATH를 대체하므로 필요한 경로를 모두 포함해야 합니다.

방화벽·백신 차단

일부 기업 환경이나 윈도우 디펜더 설정에 따라 npx가 패키지를 다운로드하지 못할 수 있습니다. 이 경우 사내 IT 담당자에게 문의하거나, 패키지를 미리 전역 설치(npm install -g 패키지명) 해두고 전역 설치 경로를 command에 직접 지정하는 방법을 사용합니다.

Claude Desktop 버전이 오래됨

MCP 지원은 비교적 최근에 추가된 기능입니다. Claude Desktop이 최신 버전인지 꼭 확인하세요. 앱 내 메뉴나 Anthropic 공식 사이트에서 확인할 수 있습니다.

자주 묻는 질문

윈도우에서 Claude Desktop MCP가 작동하지 않을 때 가장 먼저 확인할 곳은 어디인가요?

%APPDATA%\Claude\logs 폴더의 로그 파일을 먼저 확인하세요. ENOENT, spawn error, Cannot find module 등의 메시지로 원인을 빠르게 파악할 수 있습니다.

npx를 사용하는 MCP 서버인데 ‘npx를 찾을 수 없다’는 오류가 납니다. 왜 그런가요?

Claude Desktop은 시스템 PATH를 완전히 상속하지 않는 경우가 있습니다. command 값에 npx 대신 where npx 명령으로 확인한 절대 경로(예: C:\Users\사용자명\AppData\Roaming\npm\npx.cmd)를 써 보세요.

JSON 설정 파일에서 경로를 입력할 때 백슬래시를 어떻게 써야 하나요?

JSON 안에서 백슬래시 한 개(\)는 이스케이프 문자로 인식됩니다. 실제 경로 구분자로 쓰려면 반드시 이중 백슬래시(\\)를 사용하거나, 슬래시(/)로 대체해도 됩니다.

설정 파일이 없으면 직접 만들어야 하나요?

네. %APPDATA%\Claude 폴더가 없다면 Claude Desktop을 먼저 한 번 실행하면 자동으로 생성됩니다. 그 후 claude_desktop_config.json 파일이 없으면 직접 생성해 빈 JSON 객체({})부터 시작하면 됩니다.

MCP 서버를 추가했는데 Claude Desktop에 도구가 표시되지 않습니다.

JSON 문법 오류(쉼표 누락, 괄호 불일치 등)나 서버 실행 오류가 가장 흔한 원인입니다. JSON 유효성을 먼저 검사하고, 로그 파일에서 구체적인 오류 메시지를 확인하세요.

윈도우에서 uvx 기반 MCP 서버도 설치할 수 있나요?

네. uv 패키지 매니저를 먼저 설치한 뒤, command에 uvx 절대 경로를 지정하면 됩니다. npx와 동일한 PATH 이슈가 생길 수 있으므로 절대 경로를 권장합니다. 자세한 내용은 uv 공식 문서를 참고하세요.

다음 단계

Windows MCP 연결이 완료됐다면 한국 업무에 실제로 도움이 되는 서버를 탐색해 보세요.

• 코르독(KorDoc) 서버 상세 — HWP·PDF 등 공문서 변환
• HWP-MCP 서버 상세 — 한글 문서 AI 편집
• 한포지(HwpForge) 서버 상세 — HWPX AI 처리
• 개발도구 카테고리 전체 보기 — 더 많은 MCP 서버
• 전체 서버 목록 — MCP모아 서버 디렉토리