맥(macOS) Claude Desktop MCP 설정 — 파일 경로부터 연결까지 단계별
맥 Claude Desktop MCP 설정 방법을 ~/Library/Application Support/Claude 파일 경로부터 brew Node.js 설치, 실제 서버 연결까지 단계별로 안내합니다.
macOS에서 Claude Desktop에 MCP 서버를 연결하려면 ~/Library/Application Support/Claude/claude_desktop_config.json 파일을 편집하면 됩니다. Node.js(또는 Python) 런타임을 먼저 준비하고, JSON 설정 파일에 서버 정보를 등록한 뒤 Claude Desktop을 재시작하면 바로 사용할 수 있습니다. 이 가이드는 환경 준비부터 실제 서버 등록, 흔한 오류 해결까지 순서대로 안내합니다.
macOS에서 MCP가 필요한 이유
Claude Desktop은 기본적으로 텍스트 대화 기능만 제공합니다. MCP(Model Context Protocol) 서버를 연결하면 Claude가 파일 시스템, 외부 API, 데이터베이스 같은 실제 리소스에 직접 접근할 수 있게 됩니다. 예를 들어 한글(.hwp) 문서를 열거나, 공공 API를 조회하거나, 로컬 코드베이스를 분석하는 작업이 가능해집니다.
macOS 환경은 Windows와 설정 파일 경로가 다르기 때문에, 처음 설정할 때 경로를 잘못 찾아 헤매는 경우가 많습니다. 아래 단계를 따라가면 어렵지 않습니다.
준비물 한눈에 보기
| 항목 | 버전/조건 | 확인 명령 |
|---|---|---|
| macOS | 12 Monterey 이상 권장 | sw_vers |
| Claude Desktop | 최신 버전 | 앱 메뉴 → About |
| Node.js | 18 LTS 이상 | node --version |
| npm / npx | Node.js 포함 | npx --version |
| Homebrew | 선택(권장) | brew --version |
npx 기반 MCP 서버를 쓸 때는 Node.js만 있으면 됩니다. Python 기반 서버라면 uv 또는 uvx가 필요하지만, 이 가이드에서 다루는 서버들은 모두 npx를 사용합니다.
단계별 설정 방법
1단계: Homebrew와 Node.js 설치 확인
터미널(Terminal.app 또는 iTerm2)을 열고 아래 명령으로 Node.js 설치 여부를 확인합니다.
node --version
npx --version
버전이 출력되지 않으면 Homebrew로 설치합니다.
# Homebrew가 없는 경우 먼저 설치
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Node.js 설치
brew install node
설치 후 다시 node --version을 실행해 버전이 출력되면 준비 완료입니다.
2단계: Claude Desktop 설치
Claude 공식 사이트에서 macOS용 Claude Desktop 앱을 내려받아 /Applications에 설치합니다. 한 번 실행했다가 종료하면 설정 디렉터리가 자동으로 생성됩니다.
3단계: 설정 파일 경로 열기
macOS Claude Desktop의 설정 파일은 아래 경로에 있습니다.
~/Library/Application Support/Claude/claude_desktop_config.json
Finder에서 이 경로를 찾기는 번거롭습니다. 터미널에서 다음 명령으로 바로 열 수 있습니다.
# 디렉터리를 Finder로 열기
open ~/Library/Application\ Support/Claude
# 또는 VS Code로 설정 파일 바로 열기
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
파일이 없다면 직접 생성합니다.
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
4단계: claude_desktop_config.json 편집
설정 파일의 기본 구조는 다음과 같습니다. mcpServers 키 아래에 원하는 서버를 등록합니다.
{
"mcpServers": {
"서버-별칭": {
"command": "npx",
"args": ["-y", "패키지명"],
"env": {
"API_KEY": "여기에-키-입력"
}
}
}
}
아래는 실제 서버를 등록하는 예시입니다. MCP모아에서 소개하는 한글 문서 관련 서버 두 가지를 함께 등록했습니다.
{
"mcpServers": {
"kordoc": {
"command": "npx",
"args": ["-y", "kordoc", "mcp"]
},
"hwp-mcp": {
"command": "npx",
"args": ["-y", "hwp-mcp"]
}
}
}
env 키는 API 키가 필요 없는 서버라면 생략해도 됩니다.
데이터 흐름 구조
Claude Desktop
│
├─ stdio/IPC
│
▼
MCP 서버 프로세스 (npx로 실행)
│
├─ 로컬 파일 시스템 접근
└─ 외부 API 호출 (필요 시)
Claude Desktop이 설정 파일을 읽어 각 서버를 별도 프로세스로 띄우고, stdio를 통해 통신합니다. 서버가 종료되면 Claude가 자동으로 재시작을 시도합니다.
5단계: Claude Desktop 재시작
설정 파일을 저장한 뒤 Claude Desktop을 완전히 종료해야 합니다. 창을 닫는 것만으로는 백그라운드 프로세스가 남습니다.
# 터미널에서 강제 종료 후 재시작
osascript -e 'quit app "Claude"'
open -a Claude
또는 메뉴바에서 Claude → Quit Claude를 선택한 뒤 다시 실행합니다.
6단계: 연결 상태 확인
Claude Desktop이 실행되면 채팅 입력창 우측 하단에 도구(망치) 아이콘이 나타납니다. 아이콘을 클릭하면 등록된 MCP 서버 목록과 제공하는 도구들이 표시됩니다. 서버 이름이 목록에 있으면 연결 성공입니다.
맥에서만 겪는 문제와 서버별 준비 사항
터미널에서는 되는데 Claude Desktop에서는 npx를 못 찾는 이유는?
맥에서 가장 흔한 막힘입니다. 터미널은 로그인 셸 설정(.zshrc 등)을 읽어 nvm, Volta, mise 같은 도구가 만든 경로를 알지만, 아이콘을 눌러 실행한 Claude Desktop은 그 설정을 거치지 않습니다. 그래서 터미널에서 npx가 잘 돌아가도 앱에서는 npx를 찾지 못한다는 오류가 날 수 있습니다. 해결은 터미널에서 which npx로 전체 경로를 확인하고, 설정 파일의 command에 npx 대신 그 전체 경로를 적는 것입니다. Homebrew로 Node.js를 설치했다면 보통 경로가 고정되어 이 문제가 덜합니다. 더 자세한 오류 해석은 Claude MCP 연결 안될 때 해결 가이드를 참고하세요.
서버마다 command 한 줄이 왜 다른가요?
MCP모아 등록 서버를 보면 실행 방식이 서버마다 갈립니다. 2026년 11월 19일 기준 등록 192개 중 npx 방식이 56개, 파이썬 도구를 쓰는 uvx 방식이 20개, 직접 실행(stdio)이 35개, 원격 연결(http-sse)이 79개, 도커가 2개입니다. 이 글에서 다룬 한글 문서 서버는 모두 npx 한 줄이라 Node.js만 있으면 되지만, uvx 서버는 uv를, 도커 서버는 Docker Desktop을 따로 깔아야 합니다. 서버 상세 페이지의 설치 항목을 먼저 확인하고 준비물을 맞추세요.
kordoc은 setup과 mcp 중 무엇을 쓰나요?
두 명령은 역할이 다릅니다. npx -y kordoc setup은 Claude Desktop, Cursor 같은 클라이언트에 서버를 자동으로 등록해 주는 한 번만 쓰는 설치 명령입니다. 설정 파일에 직접 적을 때의 실행 명령은 args에 kordoc과 mcp를 적는 것입니다. 이 글의 예시처럼 수동으로 등록한다면 setup이 아니라 mcp를 쓰세요. 코르독은 HWP·HWPX·PDF·DOCX 등을 Markdown으로 바꾸는 서버로, 점검 결과 로컬 처리만 하고 외부 전송이 없어 안전 판정입니다.
설정 파일을 고치기 전에 백업해야 하나요?
네. 이미 여러 서버가 등록된 파일을 잘못 고치면 모든 서버가 한꺼번에 사라진 것처럼 보입니다. 편집 전에 cp 명령으로 같은 폴더에 백업본을 만들어 두면 되돌리기가 쉽습니다. 서버를 추가할 때는 mcpServers 객체 안에 항목을 이어 붙이고, 항목 사이 쉼표와 마지막 항목 뒤 쉼표 유무를 확인하세요. 파일 구조 전반은 claude_desktop_config.json 설정 가이드에 정리되어 있습니다.
연결은 됐는데 서버가 위험하지 않은지 어떻게 확인하나요?
MCP 서버는 내 컴퓨터에서 프로그램으로 실행되므로, 설치 전에 신뢰할 수 있는지 봐야 합니다. MCP모아 편집팀이 등록 서버 192개 중 129개의 소스를 직접 점검했고, 전체 기준으로 61개가 안전, 131개가 사용 주의(소스를 볼 수 없는 원격 서버 63개 포함)로 판정되었으며 회피 대상은 없었습니다. 서버 상세 페이지의 보안 점검 항목에서 외부 전송 주소와 키 저장 방식을 확인하고, 처음에는 읽기 전용 서버부터 연결하는 것을 권합니다.
애플 실리콘과 인텔 맥, 경로가 다릅니다
Homebrew가 설치되는 위치는 맥 종류에 따라 다릅니다. 애플 실리콘(M 시리즈) 맥은 보통 /opt/homebrew/bin 아래에, 인텔 맥은 /usr/local/bin 아래에 node와 npx가 생깁니다. 설정 파일에 절대 경로를 적어야 할 때는 추측하지 말고 터미널에서 직접 확인한 값을 쓰세요.
which node
which npx
예를 들어 애플 실리콘 맥에서 which npx가 /opt/homebrew/bin/npx를 출력했다면 설정의 command에 그 경로를 그대로 적습니다. 인텔 맥에서 가져온 설정 파일을 애플 실리콘 맥에 복사했다면 이 경로가 달라 서버가 뜨지 않을 수 있으니 가장 먼저 확인하세요.
파이썬 기반 서버를 쓸 때
Node.js 대신 파이썬 도구로 배포된 서버는 uvx로 실행합니다. Homebrew가 있다면 아래처럼 uv를 설치하고, 마찬가지로 which uvx로 경로를 확인합니다.
brew install uv
which uvx
설정 파일 대신 명령으로 등록하고 싶다면
Claude Code(터미널 도구)를 함께 쓴다면 설정 파일을 고치지 않고 명령으로 서버를 등록할 수 있습니다. 서버 이름 뒤에 두 개의 대시를 두고 실행 명령을 이어 적습니다. 범위를 지정하지 않으면 현재 프로젝트 전용 로컬 설정에 저장되고, 모든 프로젝트에서 쓰려면 사용자 범위로 추가합니다.
claude mcp add kordoc --scope user -- npx -y kordoc mcp
Claude Desktop과 Claude Code는 설정이 따로 관리되므로, 한쪽에 등록한 서버가 다른 쪽에 자동으로 보이지는 않습니다.
npx 실행 중 권한 오류가 날 때
npx는 사용자 캐시 폴더를 쓰기 때문에 보통 관리자 권한이 필요하지 않습니다. 권한 거부가 나온다면 sudo로 해결하려 하지 말고, 과거에 관리자 권한으로 npm을 실행해 캐시 폴더 소유자가 바뀐 것은 아닌지 확인하고 소유자를 내 계정으로 되돌리세요. 전역 설치 경로가 시스템 폴더라면 사용자 홈 아래로 바꾸는 방법도 있습니다.
흔한 오류와 해결 방법
| 증상 | 원인 | 해결 방법 |
|---|---|---|
| 도구 아이콘이 안 보임 | JSON 문법 오류 | python3 -m json.tool로 파일 검증 |
| 서버 목록에 서버 없음 | 앱을 완전히 종료 안 함 | Cmd+Q 후 재시작 |
npx: command not found | Node.js 미설치 | brew install node |
| 서버 실행 후 바로 종료 | 패키지 초기 설정 필요 | 해당 서버 문서 확인 |
| API 키 오류 | env 블록 누락 | 설정 파일에 env 추가 |
JSON 문법 오류가 가장 흔합니다. 쉼표를 마지막 키-값 쌍 뒤에 붙이거나, 따옴표를 빠뜨리는 실수가 많습니다. 파일을 저장하기 전에 반드시 검증하는 습관을 들이세요.
오류 로그를 직접 확인하려면 터미널에서 Claude Desktop 로그 파일을 열어볼 수 있습니다.
tail -f ~/Library/Logs/Claude/mcp*.log
자주 묻는 질문
claude_desktop_config.json 파일이 없으면 어떻게 하나요?
처음 설치한 경우 파일이 없을 수 있습니다. ~/Library/Application Support/Claude/ 디렉터리 안에 claude_desktop_config.json 파일을 직접 생성하면 됩니다. 디렉터리 자체가 없다면 Claude Desktop을 한 번 실행했다가 종료하면 자동으로 만들어집니다.
brew가 없어도 MCP 서버를 설치할 수 있나요?
네, 가능합니다. Node.js 공식 사이트(nodejs.org)에서 macOS PKG 설치 파일을 받아 설치하면 npx 명령을 쓸 수 있습니다. brew는 관리 편의를 위한 선택지입니다.
MCP 서버가 Claude에 나타나지 않으면 어떻게 하나요?
JSON 문법 오류가 가장 흔한 원인입니다. 설정 파일을 터미널의 python3 -m json.tool 명령으로 검증하고, Claude Desktop을 완전히 종료(Cmd+Q) 후 재시작해 보세요. 터미널에서 npx 명령을 직접 실행해 오류 메시지를 확인하는 것도 좋습니다.
여러 MCP 서버를 동시에 등록할 수 있나요?
네, mcpServers 객체 안에 키를 추가하는 방식으로 여러 서버를 등록할 수 있습니다. 각 키는 서버의 별칭이며, command/args/env 구조를 독립적으로 작성하면 됩니다.
npx -y 옵션은 무엇을 의미하나요?
npx의 -y 옵션은 패키지 설치 여부를 묻는 확인 프롬프트를 자동으로 수락합니다. MCP 서버처럼 백그라운드에서 실행되는 환경에서는 사람이 직접 입력할 수 없으므로 -y를 붙여야 정상 동작합니다.
API 키가 필요한 MCP 서버는 어떻게 설정하나요?
claude_desktop_config.json의 env 블록에 환경 변수로 API 키를 입력합니다. 키 값은 큰따옴표로 감싼 문자열로 작성하며, 파일 자체는 로컬에만 저장되고 외부로 전송되지 않습니다.
다음 단계
설정이 완료됐다면 실제 MCP 서버를 연결해 보세요. 한국 환경에 특화된 서버들이 특히 유용합니다.
- 코르독(KorDoc) — HWP·HWPX·PDF·XLSX·DOCX 등 한국 공문서를 Markdown으로 변환합니다. 설치 명령:
npx -y kordoc setup - HWP-MCP — AI가 한글(.hwp/.hwpx) 문서를 읽고 편집·생성할 수 있게 해주는 서버입니다. 설치 명령:
npx -y hwp-mcp - 한포지(HwpForge) — HWPX 문서를 AI 에이전트가 읽고 쓰고 변환할 수 있게 해주는 서버입니다. 설치 명령:
npx -y @hwpforge/mcp
더 많은 MCP 서버는 개발 도구 카테고리에서 찾아볼 수 있습니다. 직접 만든 서버가 있다면 MCP모아에 등록해 다른 개발자들과 공유해 보세요.