mcp.json 오류 해결 모음 — 백슬래시·JSON 파싱·서버 연결 실패까지
mcp.json 파싱 오류, 백슬래시 이스케이프 실수, MCP 서버 연결 실패 등 자주 발생하는 mcp.json 오류를 원인별로 진단하고 즉시 해결하는 방법을 총정리했습니다.
mcp.json 또는 claude_desktop_config.json에서 JSON 파싱 오류가 나거나 MCP 서버가 시작조차 안 될 때, 원인은 대부분 세 가지입니다. JSON 문법 실수(쉼표·따옴표·백슬래시), command에 지정한 런타임 미설치, 그리고 설정 변경 후 재시작 누락입니다. 이 가이드는 오류 유형별로 정확한 진단 방법과 즉시 적용 가능한 해결법을 제공합니다.
MCP 설정 파일의 종류와 역할
MCP 설정 파일은 사용하는 클라이언트에 따라 위치와 이름이 다릅니다. 아래 표를 먼저 확인해 자신이 편집하고 있는 파일이 올바른 것인지 점검하세요.
| 클라이언트 | 설정 파일 | 범위 |
|---|---|---|
| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | 전역(모든 대화) |
| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | 전역(모든 대화) |
| Claude Code (CLI, 프로젝트 범위) | .mcp.json (프로젝트 루트) | 프로젝트별(팀 공유) |
| Claude Code (local·user 범위) | ~/.claude.json (claude mcp add로 관리) | 나만 사용 |
두 파일 모두 JSON 형식을 사용하므로, 이 가이드에서 설명하는 JSON 문법 규칙은 공통으로 적용됩니다.
JSON 파싱 오류 — 가장 흔한 원인 4가지
MCP 서버가 전혀 인식되지 않거나 “JSON parse error” 메시지가 보인다면 설정 파일의 문법부터 확인해야 합니다.
1. 마지막 항목 뒤 쉼표 (Trailing Comma)
JSON 표준은 마지막 원소 뒤에 쉼표를 허용하지 않습니다. 많은 편집기에서 경고를 표시하지 않아 실수하기 쉽습니다.
// 잘못된 예 — 마지막 "env" 블록 뒤에 쉼표가 있음
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "some-package"],
"env": {}
},
}
}
// 올바른 예
{
"mcpServers": {
"my-server": {
"command": "npx",
"args": ["-y", "some-package"],
"env": {}
}
}
}
2. 작은따옴표 사용
JSON은 문자열 구분자로 반드시 큰따옴표(")를 사용해야 합니다. 작은따옴표(')는 유효하지 않습니다.
// 잘못된 예
{
'command': 'npx',
'args': ['-y', 'kordoc', 'setup']
}
// 올바른 예
{
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
3. Windows 경로의 백슬래시 이스케이프
JSON에서 백슬래시(\)는 이스케이프 문자로 해석됩니다. Windows 경로를 그대로 복사해 넣으면 반드시 파싱 오류가 납니다.
// 잘못된 예 — 백슬래시 한 개
{
"command": "C:\Users\username\AppData\Local\npm\npx.cmd"
}
// 올바른 예 1 — 백슬래시 두 개(이스케이프)
{
"command": "C:\\Users\\username\\AppData\\Local\\npm\\npx.cmd"
}
// 올바른 예 2 — 슬래시 사용(더 안전)
{
"command": "C:/Users/username/AppData/Local/npm/npx.cmd"
}
4. args 배열에 명령어를 통째로 넣기
npx -y kordoc mcp를 하나의 문자열로 쓰면 실행이 안 됩니다. 공백으로 구분되는 각 토큰을 배열 원소로 분리해야 합니다.
// 잘못된 예
{
"command": "npx",
"args": ["-y kordoc mcp"]
}
// 올바른 예
{
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
JSON 문법 즉시 검증하는 방법
편집 후 바로 터미널에서 문법을 확인하면 오류 줄 번호까지 정확히 알 수 있습니다.
# macOS/Linux — Claude Desktop 설정 파일 검증
python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json
# Windows (PowerShell)
Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | python3 -m json.tool
# Claude Code 프로젝트 mcp.json 검증
python3 -m json.tool .mcp.json
오류가 없으면 파싱된 JSON이 그대로 출력됩니다. 오류가 있으면 아래와 같이 몇 번째 줄인지 알려줍니다.
json.decoder.JSONDecodeError: Expecting ',' delimiter: line 8 column 3 (char 142)
MCP 서버가 JSON 문법은 맞는데 시작이 안 되는 경우
JSON 문법 검증을 통과했는데도 서버가 뜨지 않는다면, 런타임 설치 여부와 PATH 문제를 확인해야 합니다.
런타임 설치 확인
# Node.js / npx 확인
node --version
npx --version
# Python / uvx 확인
python3 --version
uvx --version
명령이 인식되지 않으면 해당 런타임을 먼저 설치해야 합니다. Node.js는 nodejs.org에서, uvx는 pip install uv로 설치합니다.
Claude Desktop에서 PATH 문제
Claude Desktop은 일반 터미널과 환경 변수가 다를 수 있습니다. 터미널에서는 npx가 잘 동작해도 Claude Desktop에서 인식 안 되는 경우, 절대 경로를 지정하는 것이 확실합니다.
# 절대 경로 확인
which npx
# 예시: /opt/homebrew/bin/npx (macOS Homebrew)
# 예시: /usr/local/bin/npx (macOS 기본)
{
"mcpServers": {
"kordoc": {
"command": "/opt/homebrew/bin/npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
실제 동작하는 설정 예시
개발도구 카테고리에 등록된 한국어 MCP 서버의 올바른 설정 예시입니다. 스펙에 명시된 설치 명령을 그대로 반영했습니다.
코르독(KorDoc) — HWP·PDF·DOCX Markdown 변환
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
HWP-MCP — 한글 문서 읽기·편집
{
"mcpServers": {
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
}
}
}
한포지(HwpForge) — HWPX 문서 AI 에이전트 연동
{
"mcpServers": {
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
여러 서버를 동시에 등록할 때는 mcpServers 객체 안에 나란히 추가합니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
},
"hwpforge": {
"command": "npx",
"args": ["-y", "@hwpforge/mcp"]
}
}
}
오류 메시지별 빠른 해결 참조표
로그 파일(macOS: ~/Library/Logs/Claude/)에서 확인할 수 있는 오류 메시지와 즉각적인 조치를 정리했습니다.
| 오류 메시지 | 원인 | 해결 방법 |
|---|---|---|
JSON parse error / SyntaxError | JSON 문법 오류 | python3 -m json.tool로 줄 번호 확인 후 수정 |
command not found | 런타임 미설치 또는 PATH 누락 | 런타임 설치 또는 절대 경로 지정 |
ENOENT: no such file or directory | 파일·디렉터리 경로 오류 | 경로 철자·슬래시 방향 재확인 |
EACCES: permission denied | 실행 권한 없음 | chmod +x 파일경로 로 권한 부여 |
Connection refused | 서버 프로세스 시작 후 포트 충돌 | 사용 중인 포트 확인 및 변경 |
| 서버가 목록에 없음 (오류 없음) | 재시작 안 함 | Claude Desktop 완전 종료 후 재시작 |
설정 변경이 반영되지 않을 때
설정 파일을 수정했는데도 MCP 서버 목록이 바뀌지 않는다면, 재시작이 누락된 것이 거의 확실합니다.
- Claude Desktop: 창 닫기만으로는 부족합니다. macOS는 메뉴 막대의 Claude 아이콘 우클릭 후 “Quit”, Windows는 시스템 트레이에서 완전 종료해야 합니다.
- Claude Code(CLI):
mcp.json은claude명령 진입 시 읽히므로, 현재 세션을 종료하고 다시claude를 실행하면 됩니다.
Claude Desktop 재시작 순서
──────────────────────────
1. mcp.json / claude_desktop_config.json 저장
2. Claude Desktop 완전 종료 (트레이 포함)
3. Claude Desktop 재시작
4. 새 대화에서 망치(도구) 아이콘 확인
오류를 줄이는 습관 두 가지
설정을 고치기 전에 백업을 남기는 이유
설정 파일은 서버가 늘어날수록 길어지고, 한 글자 실수로 전체가 무시될 수 있습니다. 편집 전에 파일을 복사해 날짜를 붙여 보관하면, 어디를 고쳤는지 비교하기도 쉽고 문제가 생겼을 때 즉시 되돌릴 수 있습니다. 특히 여러 서버를 한꺼번에 추가한 날에는 서버를 하나씩 넣고 그때마다 재시작해 확인하는 편이 원인 찾기에 유리합니다.
서버 설정을 가져다 쓸 때 확인할 점
README나 블로그의 예시를 복사해 붙일 때는 큰따옴표가 둥근 따옴표로 바뀌거나, 여러 줄이 한 줄로 합쳐지는 일이 있습니다. 붙여 넣은 직후 JSON 검사 명령으로 먼저 파싱해 보고, 서버 이름 키가 기존 서버와 겹치지 않는지도 확인하세요. 같은 이름이 두 번 나오면 뒤의 값이 앞을 덮거나 의도와 다르게 동작할 수 있습니다.
설정 파일이 여러 개일 때 헷갈리지 않는 법
같은 서버를 Claude Desktop, Claude Code, Cursor에 모두 등록하는 사람은 각 도구의 설정 파일이 서로 다른 위치에 있다는 점을 자주 잊습니다. 한 파일을 고친 뒤 다른 도구에서 확인하면 반영되지 않은 것처럼 보이므로, 어느 도구의 어느 파일을 고쳤는지 메모해 두세요. 또 같은 서버를 두 곳에 중복 등록해 두면 같은 이름의 프로세스가 여러 개 떠서 포트나 파일 접근이 충돌할 수 있으니, 사용하는 도구에만 등록하는 것이 좋습니다.
오류 메시지를 검색할 때 쓰는 요령
로그의 오류 문장 전체를 검색창에 붙여 넣기보다, 경로와 사용자 이름처럼 사람마다 다른 부분을 지우고 핵심 단어만 검색하면 같은 증상을 겪은 사례를 찾기 쉽습니다. 그다음 서버 GitHub 저장소의 이슈 검색에서 같은 문구를 찾아보면, 서버 자체의 알려진 문제인지 설정 실수인지 빨리 가릴 수 있습니다.
자주 묻는 질문
mcp.json이 뭔가요? claude_desktop_config.json과 다른 건가요?
mcp.json은 Claude Code(CLI) 환경에서 프로젝트별 MCP 설정을 저장하는 파일입니다(프로젝트 루트의 .mcp.json). 반면 claude_desktop_config.json은 Claude Desktop GUI 앱에서 전역 MCP 서버를 등록하는 파일입니다. 두 파일 모두 JSON 형식이라 문법 규칙은 동일하지만, 위치와 적용 범위가 다릅니다.
JSON 파싱 오류라고 뜨는데 어디가 잘못된 건지 모르겠어요.
터미널에서 python3 -m json.tool < 파일경로 명령을 실행하면 문법 오류가 있는 줄 번호를 정확히 알려줍니다. 가장 흔한 원인은 마지막 항목 뒤의 쉼표(trailing comma), 작은따옴표 사용, Windows 경로의 백슬래시 미이스케이프입니다.
Windows에서 경로를 넣으면 항상 파싱 오류가 납니다.
JSON에서 백슬래시는 이스케이프 문자이므로, Windows 경로의 역슬래시를 두 번 연속으로 써야 합니다. 예: C:\\Users\\username\\... 처럼 작성하거나, 슬래시(/)로 대체해도 대부분의 환경에서 정상 동작합니다.
JSON 문법은 맞는데 MCP 서버가 시작이 안 됩니다.
JSON 문법 외에도 command에 지정한 실행 파일(node, npx, uvx 등)이 설치되어 있고 PATH에 등록되어 있어야 합니다. which node 또는 where node로 경로를 확인하고, 인식이 안 된다면 절대 경로를 직접 지정해 보세요.
args 배열에 npx -y 패키지명을 어떻게 나눠서 써야 하나요?
args는 공백으로 구분되는 각 토큰을 배열 원소로 분리해서 써야 합니다. 예를 들어 npx -y kordoc setup이라면 args에 ["-y", "kordoc", "mcp"]으로 작성합니다. 하나의 문자열로 합쳐서 쓰면 실행이 안 됩니다.
설정을 바꿨는데도 변경 사항이 반영이 안 됩니다.
Claude Desktop은 설정 파일을 실행 시 한 번만 읽습니다. 수정 후에는 반드시 Claude Desktop을 완전히 종료(시스템 트레이에서도 종료)하고 다시 실행해야 합니다. Claude Code는 프로젝트 진입 시 mcp.json을 읽으므로 claude 명령을 다시 실행하면 됩니다.
다음 단계
mcp.json 오류를 해결했다면 이제 한국어 특화 MCP 서버를 추가해 보세요. 코르독(KorDoc)은 HWP·PDF·XLSX 등 한국 공문서를 Markdown으로 변환하고, HWP-MCP와 한포지(HwpForge)는 한글 문서를 AI가 직접 읽고 편집할 수 있게 해줍니다. 모두 API 키 없이 npx 한 줄로 시작 가능합니다. 더 많은 서버는 전체 서버 목록과 개발도구 카테고리에서 찾아보세요.