본문 바로가기
M MCP모아
FAQ · 2026.11.17 업데이트

Claude Desktop MCP 설치 오류 해결 — ENOENT·JSON 오류 원인과 수정법

Claude Desktop MCP 설치 오류 중 가장 흔한 ENOENT, JSON 파싱 오류의 원인을 분석하고 단계별 해결법을 안내합니다. 연결 실패·오류 로그 확인법까지 한 번에 정리했습니다.

Claude Desktop MCP 설치 오류 해결 방법을 보여주는 표지 이미지 — ENOENT와 JSON 파싱 오류 수정 과정

Claude Desktop에 MCP 서버를 설치하다가 막혔다면, 원인의 대부분은 ENOENT(파일·실행 파일 경로를 찾지 못함) 또는 JSON 파싱 오류(설정 파일 문법 오류) 두 가지입니다. 이 글에서는 두 오류의 정확한 원인을 짚고, 오류 로그를 읽는 법부터 설정 파일 수정·검증까지 단계별로 안내합니다. 다른 MCP 서버를 추가할 때도 동일한 절차를 그대로 적용할 수 있습니다.

Claude Desktop MCP 오류, 왜 발생하는가

MCP(Model Context Protocol)는 Claude Desktop이 외부 서버와 통신해 파일 읽기·API 호출 등의 기능을 확장하는 프로토콜입니다. Claude Desktop은 시작할 때 설정 파일(claude_desktop_config.json)을 파싱한 뒤, 각 MCP 서버 프로세스를 직접 실행합니다. 이 과정에서 두 가지 실패 지점이 있습니다.

[Claude Desktop 시작]
       ↓
claude_desktop_config.json 읽기 → (실패) JSON 파싱 오류
       ↓ (성공)
각 MCP 서버 command 실행 → (실패) ENOENT: 실행 파일 없음
       ↓ (성공)
MCP 서버 ↔ Claude 통신 정상

두 오류를 구분하는 것이 첫 번째 해결 단계입니다.

오류 로그 확인하기

Claude Desktop은 오류를 로그 파일에 기록합니다. 아래 경로에서 확인하세요.

운영체제로그 경로
macOS~/Library/Logs/Claude/mcp*.log
Windows%APPDATA%\Claude\logs\mcp*.log

또는 Claude Desktop 메뉴에서 Help → Open Logs Folder를 클릭하면 바로 폴더가 열립니다.

로그에서 아래 키워드를 검색하면 원인을 빠르게 파악할 수 있습니다.

로그 키워드의미
ENOENT지정한 실행 파일 경로가 없음
JSON Parse Error / SyntaxError설정 파일 문법 오류
spawn ... EACCES실행 권한 없음
Connection refused서버는 실행됐지만 포트/소켓 연결 실패

ENOENT 오류 해결하기

원인

command 필드에 지정한 실행 파일(npx, node, uvx 등)을 Claude Desktop이 찾지 못할 때 발생합니다. Claude Desktop은 시스템 PATH가 아닌 제한된 환경에서 프로세스를 실행하기 때문에, 터미널에서는 정상 동작하는 명령이 Claude에서는 ENOENT를 일으킬 수 있습니다.

해결 절차

1단계: 실제 실행 파일 경로 확인

# macOS/Linux
which npx
which node

# Windows PowerShell
where.exe npx
where.exe node

명령 실행 결과로 출력된 절대 경로를 복사해 둡니다. 예시: /usr/local/bin/npx

2단계: 설정 파일에 절대 경로 입력

설정 파일 위치:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "kordoc": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

command 값을 단순히 "npx"로 쓰면 PATH 탐색에 실패할 수 있으므로, 위에서 확인한 절대 경로를 사용하는 것이 가장 확실한 방법입니다.

3단계: Node.js가 설치되어 있는지 확인

node --version
npm --version
npx --version

버전이 출력되지 않으면 Node.js 공식 사이트에서 LTS 버전을 설치하세요.

4단계: Claude Desktop 완전 재시작

설정 파일을 저장한 뒤, Claude Desktop을 메뉴바/트레이 아이콘까지 완전히 종료하고 다시 실행합니다. 단순히 창을 닫는 것만으로는 백그라운드 프로세스가 유지됩니다.


JSON 파싱 오류 해결하기

원인

claude_desktop_config.json의 문법이 잘못됐을 때 발생합니다. 가장 흔한 실수는 다음과 같습니다.

실수 유형잘못된 예올바른 예
마지막 항목 뒤 쉼표"args": ["setup"],"args": ["setup"]
괄호 미닫힘"mcpServers": { (닫는 } 없음)모든 괄호 짝 맞춤
작은따옴표 사용'command': 'npx'"command": "npx"
Windows 경로 백슬래시"C:\Users\npx""C:\\Users\\npx"

해결 절차

1단계: JSON 문법 검사기 사용

아래 명령으로 터미널에서 즉시 검사할 수 있습니다.

# macOS/Linux
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Windows PowerShell
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | python -m json.tool

오류가 있으면 Expecting ',' delimiter: line N column M 형태로 위치를 알려줍니다.

2단계: 올바른 설정 파일 구조 확인

여러 MCP 서버를 등록할 때 구조를 정확히 맞추는 것이 중요합니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "kordoc", "mcp"]
    },
    "hwp-mcp": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}
  • 서버 항목 사이에는 쉼표(,)가 있어야 합니다.
  • 마지막 서버 항목 끝에는 쉼표가 없어야 합니다.
  • 모든 키와 문자열 값은 큰따옴표(")로 감쌉니다.

3단계: 수정 후 재검사

수정이 끝나면 1단계의 명령을 다시 실행해 No error(또는 JSON이 정상 출력)되는지 확인한 뒤 Claude Desktop을 재시작합니다.


권한 오류(EACCES) 해결

spawn ... EACCES 오류가 나타나면 실행 파일에 실행 권한이 없는 경우입니다.

# macOS/Linux: 실행 권한 부여
chmod +x /경로/to/실행파일

Windows에서는 PowerShell을 관리자 권한으로 실행하거나, 실행 파일의 속성에서 차단 해제 여부를 확인하세요.


환경별 빠른 점검 체크리스트

설정이 완료됐는데도 연결이 안 된다면 아래 항목을 순서대로 점검하세요.

□ Node.js/npm/npx 설치 확인 (node --version)
□ 설정 파일 경로가 올바른가 (OS별 다름)
□ command 값에 절대 경로 사용 여부
□ JSON 문법 검사 통과 여부 (python3 -m json.tool)
□ Claude Desktop 완전 종료 후 재시작 여부
□ 오류 로그에서 구체적 메시지 확인

한국산 MCP 서버 설치 예시

오류를 해결했다면 이제 실제 MCP 서버를 연결해 볼 차례입니다. 한국 문서 처리에 특화된 서버들을 예로 들어 설정 파일 구조를 보여드립니다.

코르독(KorDoc) — HWP·PDF를 Markdown으로 변환

코르독(KorDoc)은 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환해 Claude가 읽을 수 있게 해주는 서버입니다.

{
  "mcpServers": {
    "kordoc": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "kordoc", "mcp"]
    }
  }
}

설치 명령: npx -y kordoc setup 저장소: https://github.com/chrisryugj/kordoc

HWP-MCP — 한글 문서 읽기·편집

HWP-MCP는 AI 어시스턴트가 한글(.hwp/.hwpx) 문서를 직접 읽고 편집·생성할 수 있게 해주는 서버입니다.

{
  "mcpServers": {
    "hwp-mcp": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "hwp-mcp"]
    }
  }
}

설치 명령: npx -y hwp-mcp 저장소: https://github.com/treesoop/hwp-mcp

한포지(HwpForge) — HWPX 읽기·쓰기·변환

한포지(HwpForge)는 한글(HWPX) 문서를 AI 에이전트가 읽고 쓰고 변환할 수 있게 해주는 서버입니다.

{
  "mcpServers": {
    "hwpforge": {
      "command": "/usr/local/bin/npx",
      "args": ["-y", "@hwpforge/mcp"]
    }
  }
}

설치 명령: npx -y @hwpforge/mcp 저장소: https://github.com/ai-screams/HwpForge


자주 묻는 질문

ENOENT 오류가 무슨 뜻인가요?

ENOENT는 ‘Error NO ENTry’의 약자로, Node.js(또는 운영체제)가 지정된 파일이나 실행 파일 경로를 찾지 못할 때 발생합니다. MCP 설정 파일에서 command 값이 실제 실행 파일 위치와 다르거나, Node.js·npx가 PATH에 없을 때 주로 나타납니다.

JSON 파싱 오류는 왜 발생하나요?

claude_desktop_config.json 파일 내 문법 오류(쉼표 중복, 괄호 미닫힘, 따옴표 불일치 등)로 Claude Desktop이 설정 파일을 읽지 못할 때 발생합니다. JSON은 마지막 항목 뒤에 쉼표를 허용하지 않으므로 이 점을 특히 유의하세요.

MCP 오류 로그는 어디서 확인하나요?

macOS 기준으로 ~/Library/Logs/Claude/ 디렉토리에서 mcp*.log 파일을 확인할 수 있습니다. Windows는 %APPDATA%\Claude\logs\ 경로를 살펴보세요. Claude Desktop 상단 메뉴의 Help → Open Logs Folder를 통해 바로 열 수도 있습니다.

npx 명령어로 설치하면 매번 다운로드가 발생하나요?

npx는 캐시를 활용하므로 이미 내려받은 패키지는 재사용합니다. 단, -y 플래그와 함께 최신 버전을 명시하지 않으면 캐시 버전을 사용할 수 있습니다. 항상 최신 버전을 쓰려면 npx -y 패키지명@latest 형태로 실행하세요.

Claude Desktop을 재시작해도 MCP 서버가 연결되지 않으면 어떻게 하나요?

설정 파일 저장 후 Claude Desktop을 완전히 종료(트레이 아이콘까지 종료)하고 재시작해야 합니다. 일부 환경에서는 시스템 재부팅 후에야 PATH 변경이 반영됩니다. 오류 로그를 다시 확인해 ENOENT인지 JSON 오류인지 구분한 뒤 해당 절차를 따르세요.

Windows에서 경로 구분자를 어떻게 써야 하나요?

JSON 안에서 Windows 경로를 쓸 때는 백슬래시를 두 번 써야 합니다(예: C:\\Users\\yourname). 또는 슬래시(/)로 대체할 수 있습니다. 한 개의 백슬래시만 쓰면 JSON 파싱 오류가 납니다.


다음 단계

오류를 해결했다면 본격적으로 MCP 서버를 활용해 보세요.

이 글과 관련된 MCP 서버