맥(macOS) Claude Desktop MCP 설정 — 파일 경로부터 연결까지 단계별

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.ai에서 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", "setup"]
    },
    "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 서버 목록과 제공하는 도구들이 표시됩니다. 서버 이름이 목록에 있으면 연결 성공입니다.

흔한 오류와 해결 방법

증상	원인	해결 방법
도구 아이콘이 안 보임	JSON 문법 오류	jsonlint.com으로 파일 검증
서버 목록에 서버 없음	앱을 완전히 종료 안 함	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 문법 오류가 가장 흔한 원인입니다. 설정 파일을 jsonlint.com 같은 도구로 검증하고, 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모아에 등록해 다른 개발자들과 공유해 보세요.

전체 서버 목록 보기 · 가이드 전체 보기