claude_desktop_config.json 설정법 — MCP 서버 JSON 완전 정복
claude_desktop_config.json 파일 경로와 mcpServers JSON 작성법을 단계별로 설명합니다. Claude Desktop에 MCP 서버를 추가·수정·삭제하는 방법을 실제 예시와 함께 완전히 정리했습니다.
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", "mcp"]
}
}
}
HWP-MCP처럼 한글 문서를 직접 읽고 편집하는 서버도 같은 방식으로 등록합니다.
{
"mcpServers": {
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
}
}
}
3단계 — 여러 서버 동시 등록
mcpServers 객체에 키를 여러 개 넣으면 됩니다. 서버들은 독립 프로세스로 동시에 실행됩니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"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": "여기에_실제_키_입력"
}
}
}
}
uvx 방식과 로컬 파일 방식 서버 등록
Python 기반 서버는 uvx로 실행하는 경우가 많습니다. command를 uvx로 두고 args에 패키지 이름을 넣으며, 필요하면 env로 키를 전달합니다. 이 방식은 uv가 설치돼 있어야 하며, 설치 후 터미널을 다시 열어 PATH를 갱신해야 합니다.
{
"mcpServers": {
"python-server": {
"command": "uvx",
"args": ["패키지명@latest"]
}
}
}
npm이나 PyPI에 배포되지 않고 저장소를 직접 내려받아 실행하는 서버라면, command에 인터프리터(node, python3, uv 등)를 두고 args에 실행 파일의 절대 경로를 적습니다. 상대 경로는 Claude Desktop이 실행되는 위치를 기준으로 해석되기 때문에 대개 실패합니다.
{
"mcpServers": {
"my-local-server": {
"command": "node",
"args": ["/Users/사용자명/projects/my-mcp-server/index.js"]
}
}
}
Windows에서는 JSON 문자열 안의 역슬래시를 두 번 연속(\\)으로 써야 합니다. JSON에서 역슬래시가 이스케이프 문자이기 때문이며, command에 npx나 node처럼 PATH에 잡힌 명령을 쓸 때는 경로가 아니므로 해당하지 않습니다.
{
"mcpServers": {
"my-local-server": {
"command": "node",
"args": ["C:\\Users\\사용자명\\projects\\my-mcp-server\\index.js"]
}
}
}
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 서버가 제공하는 도구 이름이 나열되면 설정이 완료된 것입니다.
설정 파일에서 자주 나오는 JSON 실수
| 실수 유형 | 잘못된 예 | 올바른 예 |
|---|---|---|
| 마지막 항목 뒤 쉼표 | "args": ["a", "b",] | "args": ["a", "b"] |
| 키에 따옴표 누락 | {mcpServers: {}} | {"mcpServers": {}} |
| 작은따옴표 사용 | 'command': 'npx' | "command": "npx" |
| 중괄호 불일치 | 열기만 하고 닫지 않음 | 모든 중괄호 쌍 맞추기 |
VS Code에서 파일을 열었을 때 빨간 밑줄이 없으면 문법은 대체로 맞습니다. 서버를 한 번에 하나씩 추가하고 그때마다 재시작해 확인하면, 오류가 생겼을 때 어느 항목이 원인인지 바로 알 수 있습니다.
키가 든 설정 파일의 권한 관리
env에 API 키를 직접 적는 파일은 다른 사용자가 읽지 못하게 제한하는 편이 좋습니다. macOS와 Linux에서는 아래 명령으로 본인만 읽고 쓰도록 바꿀 수 있습니다. 혼자 쓰는 PC에서는 위험이 크지 않지만, 이 파일을 Git에 올리거나 다른 사람과 공유할 때는 키를 반드시 제거하세요.
chmod 600 ~/Library/Application\ Support/Claude/claude_desktop_config.json
Claude Code는 이 파일을 쓰지 않습니다
Claude Code(CLI)를 함께 쓴다면 반드시 구분해야 합니다. claude_desktop_config.json은 Claude Desktop 앱 전용이며, Claude Code는 이 파일을 읽지 않습니다. Claude Code에서는 claude mcp add 명령으로 서버를 등록합니다. 실행 명령 앞에는 --를 붙여 Claude Code 옵션과 서버 인자를 구분합니다.
# 서버 추가 (npx 방식 예시)
claude mcp add kordoc -- npx -y kordoc mcp
# 등록된 서버 목록 확인
claude mcp list
# 서버 제거
claude mcp remove kordoc
등록 범위는 기본 local(내 계정, 해당 프로젝트)이고, --scope project를 쓰면 프로젝트 루트의 .mcp.json에 기록되어 팀과 공유할 수 있으며, --scope user는 모든 프로젝트에 적용됩니다. 원격 서버는 claude mcp add --transport http <이름> <URL>로 등록합니다. settings.json은 서버 정의를 넣는 곳이 아니므로 그곳에 mcpServers를 적어도 인식되지 않습니다. 두 도구의 설정은 서로 독립적이고, command·args·env를 쓰는 규칙만 비슷합니다.
개발용과 배포용 서버를 나눠 관리하기
직접 만드는 서버를 개발하는 중이라면 개발용과 실제 사용 서버를 이름으로 구분하면 편합니다. 서버 이름에 -dev 같은 접미사를 붙이면 도구 목록에서 어느 쪽인지 바로 보입니다. 개발용은 로컬 파일 경로로, 안정화된 서버는 npx로 등록하는 식입니다. 임시로 끄고 싶을 때는 항목을 지우는 대신 별도 파일에 보관해 두었다가 되돌리는 방법이 안전합니다. 설정 파일에는 공식적인 비활성화 키가 없으므로 이름 앞에 특수 문자를 붙이는 식의 임시 방법은 버전에 따라 오류를 낼 수 있습니다.
흔한 오류와 해결법
| 증상 | 원인 | 해결 |
|---|---|---|
| MCP 서버가 도구 목록에 안 보임 | 완전 재시작 안 함, 또는 JSON 오류 | 완전 종료 후 재실행, jq로 JSON 검증 |
| Claude Desktop이 시작 시 멈춤 | mcpServers 키 오타 또는 전체 JSON 파싱 실패 | 파일 내용을 통째로 jq .에 붙여 오류 위치 확인 |
| 특정 서버만 안 보임 | 해당 서버의 command/args 오류, 또는 npx 미설치 | 해당 서버의 명령을 터미널에서 직접 실행해 오류 확인 |
| ”spawn npx ENOENT” 오류 | Node.js 미설치 또는 PATH 문제 | node --version으로 설치 확인, 필요시 전체 경로 사용 |
| 환경변수가 서버에 전달 안 됨 | env 키 오타 또는 값에 따옴표 누락 | JSON에서 모든 문자열 값은 큰따옴표로 감싸야 함 |
서버가 “오프라인”으로 표시되거나 도구 실행이 실패할 때
대부분 실행 파일 경로 문제입니다. node --version과 npx --version으로 런타임이 설치돼 있는지 확인하고, 설치돼 있는데도 실패하면 command를 which npx로 확인한 절대 경로로 바꿔 봅니다. 로컬 파일 방식이라면 경로가 정확한지, 파일이 실제로 존재하는지도 확인하세요. 서버를 터미널에서 같은 명령으로 직접 실행해 보면 Claude 화면에는 나오지 않는 오류 메시지를 볼 수 있습니다.
npx를 찾지 못하는 경우
일부 환경에서는 command에 npx만 쓰면 Claude Desktop이 실행 경로를 못 찾습니다. 이럴 때는 전체 경로를 사용합니다.
# npx 경로 확인
which npx
출력된 경로(예: /usr/local/bin/npx)를 command 값에 그대로 사용합니다.
{
"mcpServers": {
"kordoc": {
"command": "/usr/local/bin/npx",
"args": ["-y", "kordoc", "mcp"]
}
}
}
설정 파일 전체 예시
실제 운영 환경에서 사용할 수 있는 완성된 예시입니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"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모아에 등록해 한국 개발자 커뮤니티와 공유해 보세요.