claude_desktop_config.json 설정법 — MCP 서버 JSON 완전 정복

Q: claude_desktop_config.json 파일이 없으면 어떻게 하나요?

처음 Claude Desktop을 설치하면 파일이 없을 수 있습니다. 해당 경로(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)에 직접 claude_desktop_config.json 파일을 새로 만들고 기본 JSON 구조를 작성하면 됩니다.

Q: 여러 개의 MCP 서버를 동시에 등록할 수 있나요?

네, mcpServers 객체 안에 키(서버 이름)를 여러 개 추가하면 됩니다. 각 서버는 독립적으로 동작하며, Claude Desktop이 모두 동시에 연결을 시도합니다.

Q: API 키 같은 비밀 값을 JSON에 직접 넣어도 되나요?

claude_desktop_config.json은 로컬 파일이므로 본인 컴퓨터에서만 사용한다면 기능적으로는 동작합니다. 다만 이 파일을 GitHub 등 공개 저장소에 올리면 키가 노출되므로 주의가 필요합니다. 운영체제 환경변수로 관리하거나 .gitignore에 추가하는 것을 권장합니다.

Q: JSON 문법 오류를 어떻게 찾나요?

터미널에서 'cat ~/Library/Application Support/Claude/claude_desktop_config.json | jq .' 명령으로 확인할 수 있습니다. jq가 없으면 jsonlint.com 같은 온라인 도구를 이용하세요. 오류 위치를 줄 번호로 알려줍니다.

Q: command 값에 npx 대신 node나 python을 써야 하는 경우가 있나요?

네, 패키지 방식이 아니라 직접 스크립트를 실행하는 서버는 command에 node나 python3를, args에 스크립트 경로를 넣습니다. 각 MCP 서버의 공식 README에 명시된 설정 방법을 따르는 것이 가장 정확합니다.

Claude Desktop에서 MCP 서버를 연결하려면 claude_desktop_config.json 파일 하나만 올바르게 작성하면 됩니다. 이 파일의 위치, JSON 구조, 서버 등록 방법, 자주 발생하는 오류와 해결책까지 이 글 하나로 완전히 정리했습니다. 설정을 마치면 Claude Desktop 채팅창에서 MCP 서버가 제공하는 도구를 바로 사용할 수 있습니다.

claude_desktop_config.json이란?

claude_desktop_config.json은 Claude Desktop 앱이 읽는 로컬 설정 파일입니다. 핵심 역할은 어떤 MCP 서버를 어떻게 실행할지 알려주는 것입니다. Claude Desktop은 시작 시 이 파일을 파싱하여 파일에 정의된 MCP 서버를 자동으로 실행하고 연결합니다.

MCP(Model Context Protocol)는 Anthropic이 설계한 개방형 프로토콜로, 외부 도구·데이터 소스를 AI 모델에 연결하는 표준 방식입니다. claude_desktop_config.json은 그 연결의 시작점이 되는 파일이라고 이해하면 됩니다.

사용자 요청
    ↓
Claude Desktop
    ↓  (claude_desktop_config.json 읽기)
MCP 서버 프로세스 실행
    ↓
외부 도구 / 한국 API / 로컬 파일

파일 경로 확인하기

운영체제별 파일 위치가 다릅니다. 먼저 경로를 확인하세요.

운영체제	파일 경로
macOS	`~/Library/Application Support/Claude/claude_desktop_config.json`
Windows	`%APPDATA%\Claude\claude_desktop_config.json`
Linux	`~/.config/Claude/claude_desktop_config.json` (비공식 빌드)

macOS에서 터미널로 빠르게 열려면 아래 명령을 사용합니다.

open ~/Library/Application\ Support/Claude/

Windows에서는 파일 탐색기 주소창에 %APPDATA%\Claude\를 입력하면 됩니다.

파일이 없는 경우 해당 디렉터리에 claude_desktop_config.json이라는 이름으로 새 파일을 직접 만들면 됩니다.

기본 JSON 구조

파일의 최상위는 JSON 객체이고, mcpServers 키 아래에 각 서버를 등록합니다.

{
  "mcpServers": {
    "서버이름": {
      "command": "실행명령",
      "args": ["인수1", "인수2"],
      "env": {
        "환경변수명": "값"
      }
    }
  }
}

mcpServers — 필수 최상위 키. 이 키가 없으면 Claude Desktop은 MCP 서버를 찾지 않습니다.
서버이름 — 임의의 식별자. Claude Desktop 도구 목록에 표시되는 이름입니다.
command — 서버를 실행할 명령어. 주로 npx, uvx, node, python3 중 하나입니다.
args — 명령에 전달할 인수 배열.
env — 환경변수. API 키처럼 명령줄에 넣기 어려운 값을 전달할 때 사용합니다.

단계별 설정 방법

1단계 — 파일 열기 또는 생성

터미널(macOS)에서 VS Code로 파일을 열거나 새로 만듭니다.

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

파일이 이미 존재하면 기존 내용을 보존하면서 mcpServers 블록에 서버를 추가합니다.

2단계 — npx 방식 서버 등록

Node.js 기반의 MCP 서버는 대부분 npx로 실행합니다. -y 플래그는 설치 확인 질문에 자동으로 yes를 응답합니다.

아래는 코르독(KorDoc) 서버를 등록하는 예시입니다. 코르독은 HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환해 주는 MCP 서버입니다.

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

HWP-MCP처럼 한글 문서를 직접 읽고 편집하는 서버도 같은 방식으로 등록합니다.

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

3단계 — 여러 서버 동시 등록

mcpServers 객체에 키를 여러 개 넣으면 됩니다. 서버들은 독립 프로세스로 동시에 실행됩니다.

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

위 예시는 한포지(HwpForge)까지 세 개의 한국 문서 관련 서버를 한 번에 등록한 모습입니다.

4단계 — 환경변수(API 키) 추가

API 키가 필요한 서버는 env 블록에 넣습니다.

{
  "mcpServers": {
    "my-api-server": {
      "command": "npx",
      "args": ["-y", "패키지명"],
      "env": {
        "API_KEY": "여기에_실제_키_입력"
      }
    }
  }
}

5단계 — JSON 유효성 검증

저장 전에 반드시 JSON 문법을 확인합니다. 쉼표 하나가 빠지거나 중괄호가 닫히지 않으면 Claude Desktop이 설정을 아예 읽지 못합니다.

macOS/Linux 터미널에서 jq로 빠르게 확인할 수 있습니다.

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

오류가 없으면 JSON 내용이 보기 좋게 출력됩니다. 오류가 있으면 줄 번호와 함께 오류 메시지가 표시됩니다.

6단계 — Claude Desktop 완전 재시작

설정 변경은 Claude Desktop을 완전히 종료하고 다시 실행해야 반영됩니다. 창을 닫는 것만으로는 부족합니다.

macOS — 메뉴바(상단 오른쪽)의 Claude 아이콘 우클릭 → Quit Claude 선택
Windows — 시스템 트레이(우하단)의 Claude 아이콘 우클릭 → 종료

재시작 후 채팅창에서 망치(도구) 아이콘이 보이면 MCP 서버가 정상 연결된 것입니다.

7단계 — 연결 확인

Claude에게 직접 물어보는 것이 가장 빠릅니다.

“지금 사용할 수 있는 도구 목록을 알려줘.”

등록된 MCP 서버가 제공하는 도구 이름이 나열되면 설정이 완료된 것입니다.

흔한 오류와 해결법

증상	원인	해결
MCP 서버가 도구 목록에 안 보임	완전 재시작 안 함, 또는 JSON 오류	완전 종료 후 재실행, `jq`로 JSON 검증
Claude Desktop이 시작 시 멈춤	`mcpServers` 키 오타 또는 전체 JSON 파싱 실패	파일 내용을 통째로 `jq .`에 붙여 오류 위치 확인
특정 서버만 안 보임	해당 서버의 `command`/`args` 오류, 또는 npx 미설치	해당 서버의 명령을 터미널에서 직접 실행해 오류 확인
”spawn npx ENOENT” 오류	Node.js 미설치 또는 PATH 문제	`node --version`으로 설치 확인, 필요시 전체 경로 사용
환경변수가 서버에 전달 안 됨	`env` 키 오타 또는 값에 따옴표 누락	JSON에서 모든 문자열 값은 큰따옴표로 감싸야 함

npx를 찾지 못하는 경우

일부 환경에서는 command에 npx만 쓰면 Claude Desktop이 실행 경로를 못 찾습니다. 이럴 때는 전체 경로를 사용합니다.

# npx 경로 확인
which npx

출력된 경로(예: /usr/local/bin/npx)를 command 값에 그대로 사용합니다.

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

설정 파일 전체 예시

실제 운영 환경에서 사용할 수 있는 완성된 예시입니다.

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

이 세 서버는 모두 API 키 없이 사용할 수 있으며, devtools 카테고리에서 더 많은 MCP 서버를 찾아볼 수 있습니다.

자주 묻는 질문

claude_desktop_config.json 파일이 없으면 어떻게 하나요?

처음 Claude Desktop을 설치하면 파일이 없을 수 있습니다. 해당 경로(macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\)에 직접 claude_desktop_config.json 파일을 새로 만들고 위에서 설명한 기본 JSON 구조를 작성하면 됩니다. 디렉터리 자체가 없다면 디렉터리도 먼저 만들어야 합니다.

설정을 저장했는데 MCP 서버가 안 보여요.

Claude Desktop을 ‘완전히’ 재시작해야 합니다. 창을 닫는 것만으로는 부족하고, macOS는 메뉴바 아이콘에서 Quit, Windows는 트레이 아이콘 우클릭 후 종료해야 합니다. 재시작 후에도 안 보이면 JSON 문법 오류가 없는지 jq로 확인하세요.

여러 개의 MCP 서버를 동시에 등록할 수 있나요?

네, mcpServers 객체 안에 키(서버 이름)를 여러 개 추가하면 됩니다. 각 서버는 독립적으로 동작하며, Claude Desktop이 모두 동시에 연결을 시도합니다. 서버 수에 별도 제한은 없지만 많을수록 시작 시간이 길어질 수 있습니다.

API 키 같은 비밀 값을 JSON에 직접 넣어도 되나요?

claude_desktop_config.json은 로컬 파일이므로 본인 컴퓨터에서만 사용한다면 기능적으로는 동작합니다. 다만 이 파일을 GitHub 등 공개 저장소에 올리면 키가 노출되므로 주의가 필요합니다. 파일을 버전 관리한다면 .gitignore에 추가하는 것을 권장합니다.

JSON 문법 오류를 어떻게 찾나요?

터미널에서 아래 명령으로 확인할 수 있습니다.

cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .

jq가 없으면 jsonlint.com 같은 온라인 도구를 이용하세요. 오류 위치를 줄 번호로 알려줍니다.

command 값에 npx 대신 node나 python을 써야 하는 경우가 있나요?

네, 패키지 방식이 아니라 직접 스크립트를 실행하는 서버는 command에 node나 python3를, args에 스크립트 경로를 넣습니다. 각 MCP 서버의 공식 README에 명시된 설정 방법을 따르는 것이 가장 정확합니다.

다음 단계

claude_desktop_config.json 설정을 마쳤다면, 이제 실제 MCP 서버를 하나씩 추가해 보세요.

한국 문서 처리: 코르독(KorDoc), HWP-MCP, 한포지(HwpForge)는 모두 API 키 없이 바로 사용할 수 있습니다.
더 많은 서버 탐색: MCP 서버 전체 목록이나 devtools 카테고리에서 원하는 서버를 찾아보세요.
새 서버 등록: 직접 만든 MCP 서버가 있다면 MCP모아에 등록해 한국 개발자 커뮤니티와 공유해 보세요.