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 서버를 활용해 보세요.
- devtools 카테고리에서 개발 도구 MCP 서버를 더 찾아보세요.
- MCP 서버 전체 목록에서 원하는 서버를 검색할 수 있습니다.
- 가이드 목록에서 다른 설치·연동 튜토리얼을 확인하세요.
- 직접 개발한 MCP 서버가 있다면 서버 등록하기를 통해 MCP모아에 등록해 보세요.