본문 바로가기
M MCP모아
튜토리얼 · 2026.11.17 업데이트

MCP 서버 Windows 설치 가이드 — 백슬래시·경로 오류 없이 설정하는 법

Windows에서 MCP 서버 설치 시 발생하는 백슬래시·경로 오류를 단계별로 해결합니다. Claude Desktop 설정 파일 위치부터 Node.js 환경 구성, 흔한 실패 패턴까지 완벽 정리.

Windows 환경에서 MCP 서버를 설치하고 Claude Desktop에 연결하는 단계별 설정 흐름도

Windows 환경에서 MCP 서버를 처음 설치하다 보면 맥(Mac)에서는 없던 문제들이 연속으로 터집니다. 백슬래시 경로 오류, npx를 찾지 못하는 문제, Claude Desktop이 설정을 인식하지 못하는 현상이 대표적입니다. 이 가이드는 Windows 10/11 기준으로 MCP 서버를 처음부터 설정하는 전 과정을 단계별로 안내하고, 발생 빈도가 높은 오류를 한 번에 해결합니다.

Claude Desktop 앱 자체의 다운로드와 설치, 로그인이 아직이라면 Claude Desktop 설치 방법을 먼저 따라 하세요. 이 글은 앱 설치를 마친 뒤 MCP 서버를 Windows에서 오류 없이 등록하는 방법만 다룹니다.

Windows에서 MCP 설치가 까다로운 이유

MCP(Model Context Protocol) 서버 대부분은 Node.js 기반으로 만들어져 있고, 공식 문서가 Mac/Linux 환경을 기준으로 작성된 경우가 많습니다. Windows에서 추가로 신경 써야 하는 부분이 몇 가지 있습니다.

구분Mac/LinuxWindows
경로 구분자/ (슬래시)\ (백슬래시)
설정 파일 위치~/Library/Application Support/Claude/%APPDATA%\Claude\
환경 변수.bashrc / .zshrc시스템 환경 변수 또는 PowerShell 프로파일
셸 기본값bash/zshcmd.exe / PowerShell

이 차이를 모르고 그냥 복붙하면 JSON 파싱 오류나 경로 인식 실패가 납니다. 아래 단계를 순서대로 따라오시면 됩니다.

준비물

  • Windows 10 22H2 이상 또는 Windows 11
  • Claude Desktop 최신 버전 (claude.ai/download)
  • Node.js 18 LTS 이상 (nodejs.org)
  • 텍스트 에디터: VS Code, Notepad++ 등 (메모장은 인코딩 문제가 생길 수 있음)

단계별 설치 방법

1단계: Node.js 설치 및 PATH 확인

Node.js 공식 사이트에서 Windows용 LTS 설치 파일(.msi)을 내려받아 실행합니다. 설치 중 “Add to PATH” 옵션이 체크되어 있는지 반드시 확인하세요. 설치가 끝나면 PowerShell을 새로 열고 아래 명령어로 확인합니다.

node -v
npm -v
npx -v

세 명령 모두 버전 번호가 출력되면 정상입니다. 'npx'은(는) 내부 또는 외부 명령... 오류가 뜨면 Node.js를 재설치하거나, 시스템 환경 변수 PATH에 Node.js 설치 경로를 직접 추가해야 합니다.

2단계: Claude Desktop 설정 파일 위치 확인

Claude Desktop의 MCP 설정 파일은 다음 경로에 있습니다.

C:\Users\[사용자명]\AppData\Roaming\Claude\claude_desktop_config.json

Windows 탐색기 주소창에 %APPDATA%\Claude 를 입력하면 바로 이동할 수 있습니다. claude_desktop_config.json 파일이 없으면 직접 생성해야 합니다. 메모장이 아닌 VS Code나 Notepad++을 사용하면 UTF-8 BOM 없이 저장할 수 있어 안전합니다.

3단계: 설정 파일 작성 — 경로 규칙이 핵심

설정 파일의 기본 구조는 다음과 같습니다.

{
  "mcpServers": {
    "서버이름": {
      "command": "npx",
      "args": ["-y", "패키지명"]
    }
  }
}

Windows 경로를 직접 지정할 때의 규칙:

경로에 백슬래시를 사용해야 한다면, JSON 안에서 반드시 두 번 써야 합니다(\\). 또는 슬래시(/)로 대체해도 Node.js가 올바르게 인식합니다.

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["C:/Users/사용자명/my-mcp-server/index.js"]
    }
  }
}

또는 이스케이프 방식으로:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["C:\\Users\\사용자명\\my-mcp-server\\index.js"]
    }
  }
}

두 방식 모두 동작하지만, 슬래시 방식이 훨씬 실수가 적습니다.

4단계: npx 기반 MCP 서버 설치 예시

npx로 실행하는 MCP 서버는 경로 문제가 없어 Windows에서도 간편합니다. 예를 들어 코르독(KorDoc) 서버를 추가하려면 설정 파일을 다음과 같이 작성합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

HWP-MCP 서버를 추가하는 경우:

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

여러 서버를 동시에 등록하려면 mcpServers 객체 안에 나란히 추가합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "npx",
      "args": ["-y", "kordoc", "mcp"]
    },
    "hwp-mcp": {
      "command": "npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

5단계: Claude Desktop 완전 재시작

설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료해야 합니다. 창을 닫는 것만으로는 부족합니다. Windows 작업 표시줄 우측 하단의 트레이 아이콘을 우클릭하여 종료(Quit) 를 선택한 다음 다시 실행하세요. Claude Desktop이 열리면 대화창에서 망치 아이콘이 표시되면 MCP 서버가 정상 연결된 것입니다.


흔한 오류와 해결 방법

오류 1: JSON 파싱 실패 (SyntaxError)

설정 파일을 저장했는데 Claude Desktop이 오류를 내뱉는다면 JSON 문법 오류일 가능성이 높습니다.

오류 메시지 예: SyntaxError: Unexpected token \ in JSON

해결: JSON 유효성 검사기(jsonlint.com 등)에 설정 파일 내용을 붙여 넣어 확인하세요. 쉼표 누락, 따옴표 불일치, 백슬래시 단일 사용이 주요 원인입니다.

오류 2: npx를 찾을 수 없음

오류 메시지 예: 'npx'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다.

해결 순서:

  1. PowerShell을 관리자로 실행하여 node -v 확인
  2. 출력이 없으면 Node.js 재설치 (Add to PATH 체크 필수)
  3. 재설치 후 시스템 재시작(로그오프 후 재로그인)

오류 3: 한글 경로가 포함된 경우

사용자 이름이나 폴더명에 한글이 들어가면 일부 MCP 서버에서 인식 오류가 발생할 수 있습니다. 가급적 영문 경로에 MCP 서버 파일을 두는 것을 권장합니다. 예를 들어 C:\mcp-servers\ 같은 루트 근처 폴더를 사용하면 안전합니다.

오류 4: 방화벽/백신 프로그램 차단

회사 PC나 보안 소프트웨어가 설치된 환경에서는 npx 실행 중 네트워크 다운로드가 차단될 수 있습니다. 이 경우 백신 프로그램의 예외 목록에 Node.js 설치 경로를 추가하거나, IT 담당자에게 허용 요청을 합니다.


데이터 흐름 구조

Windows에서 MCP 서버가 동작하는 구조를 간단히 표현하면 다음과 같습니다.

Claude Desktop (Windows)
    │
    ├─ claude_desktop_config.json 읽기
    │   (%APPDATA%\Claude\)
    │
    ├─ npx 실행 → MCP 서버 프로세스 시작
    │   (Node.js via PATH)
    │
    └─ MCP 프로토콜 통신 (stdio)
           │
           └─ 외부 API / 로컬 파일 시스템 접근

이 흐름에서 문제가 가장 자주 발생하는 지점은 npx 실행 단계(PATH 문제)와 설정 파일 읽기 단계(JSON 오류)입니다.


회사 Windows PC에서 추가로 부딪히는 문제

실행 정책과 보안 프로그램은 어디서 확인하나요?

PowerShell 스크립트 실행이 막혀 있으면 npx 가 스크립트 파일 형태로 실행되다가 실패하는 경우가 있습니다. 이럴 때는 PowerShell 대신 명령 프롬프트에서 같은 명령을 시험해 보세요. 그래도 막히면 회사 보안 정책이 원인일 가능성이 크므로, 개인 설정으로 우회하기보다 IT 담당자에게 허용 범위를 문의하는 것이 안전합니다.

Windows에서 한글 문서 서버를 시험해 보는 순서

처음에는 외부 키가 필요 없는 서버 하나만 넣어 연결 자체를 검증하세요. 코르독(kordoc)이나 HWP-MCP는 npx 한 줄로 실행되고 로컬에서만 동작하므로 가장 변수가 적습니다. 연결이 확인된 뒤에 API 키가 필요한 서버를 추가하면, 문제가 생겼을 때 원인이 경로인지 키인지 구분하기 쉽습니다.

자주 묻는 질문

Windows에서 MCP 설정 파일 위치가 어디인가요?

Claude Desktop의 설정 파일은 C:\Users\사용자명\AppData\Roaming\Claude\claude_desktop_config.json 에 있습니다. 탐색기 주소창에 %APPDATA%\Claude 를 입력하면 바로 이동할 수 있습니다.

경로에 백슬래시를 쓰면 왜 오류가 나나요?

JSON에서 백슬래시(\)는 이스케이프 문자로 처리되므로, 하나만 쓰면 잘못된 JSON이 됩니다. 슬래시(/)로 대체하거나 백슬래시를 두 번 연속(\\) 써야 합니다.

npx 명령을 인식하지 못한다고 나옵니다. 어떻게 해야 하나요?

Node.js가 PATH에 제대로 등록되지 않은 경우입니다. Node.js를 공식 사이트(nodejs.org)에서 재설치하고, 설치 옵션 중 ‘Add to PATH’를 반드시 체크하세요. 설치 후 터미널을 새로 열어 node -v 명령으로 확인합니다.

MCP 서버를 추가했는데 Claude Desktop에서 인식이 안 됩니다.

Claude Desktop을 완전히 종료(트레이 아이콘 우클릭 → 종료)한 후 다시 시작해야 합니다. 단순히 창을 닫으면 백그라운드에서 계속 실행되어 설정이 반영되지 않습니다.

PowerShell과 CMD 중 어디서 실행해야 하나요?

둘 다 사용할 수 있지만, PowerShell을 권장합니다. npm/npx 명령어 모두 PowerShell에서 잘 동작하며, 오류 메시지도 더 명확하게 출력됩니다.

회사 PC라서 관리자 권한이 없는데 설치할 수 있나요?

nvm-windows(Node Version Manager for Windows)를 사용하면 관리자 권한 없이도 Node.js를 사용자 디렉터리에 설치할 수 있습니다. 다만 회사 보안 정책에 따라 제한이 있을 수 있으니 IT 팀과 먼저 확인하세요.


다음 단계

Windows 설정이 완료됐다면, 이제 실제로 MCP 서버를 연결해 볼 차례입니다. 한국 업무 환경에 특화된 서버들을 살펴보세요.

  • 코르독(KorDoc) — HWP·HWPX·PDF·DOCX 등 한국 공문서를 Claude가 읽을 수 있도록 변환
  • HWP-MCP — 한글(.hwp/.hwpx) 문서를 AI가 직접 읽고 편집
  • 한포지(HwpForge) — HWPX 문서를 AI 에이전트가 읽고 쓰고 변환

더 많은 한국어 MCP 서버는 개발 도구 카테고리에서 확인하거나, 전체 서버 목록을 둘러보세요. 새로운 MCP 서버를 발견했다면 가이드 모음에서 다른 설치 가이드도 참고하실 수 있습니다.

이 글과 관련된 MCP 서버