Claude Desktop에서 Model Context Protocol (MCP) 설정 및 활용
Claude Desktop은 Anthropic이 개발한 차세대 AI 비서로서, 사용자의 작업을 지원하기 위해 안전성, 정확성, 보안을 중시하여 설계되었습니다.
Model Context Protocol (MCP)이란 무엇인가?
Model Context Protocol (MCP)은 Claude와 같은 AI 모델이 로컬 시스템, 애플리케이션, 그리고 데이터와 상호 작용할 수 있도록 하는 핵심 프로토콜입니다. 이는 AI가 사용자의 실제 작업 환경에 대한 "눈과 귀" 역할을 수행하게 함으로써, 모델이 주변 컨텍스트에 접근하고 다양한 도구를 활용할 수 있도록 합니다. MCP 서버는 Claude Desktop이 시작될 때마다 자동으로 실행되도록 구성 파일에 정의되며, 일반적으로 Node.js의 npx 명령을 통해 설치 및 실행될 수 있습니다.
MCP를 통해 Claude Desktop의 기능은 비약적으로 확장됩니다. 사용자는 로컬 애플리케이션과 직접 상호 작용하고, 민감한 비공개 데이터에 접근하며, 개발 도구와 원활하게 통합할 수 있게 됩니다.
Claude Desktop에 MCP를 통합하는 것은 AI의 능력을 단순한 클라우드 기반 정보 처리를 넘어 사용자의 개인적인 작업 환경과 긴밀하게 연결하는 것을 의미합니다. 이는 AI가 사용자의 특정 컨텍스트를 깊이 이해하고, 이에 기반한 개인화된 작업을 수행하며, 민감한 데이터를 외부로 전송할 필요 없이 로컬에서 처리할 수 있는 '로컬 인텔리전스'를 갖추게 합니다. 이러한 능력은 생산성 향상뿐만 아니라 데이터 프라이버시 및 보안 측면에서도 상당한 이점을 제공합니다. 특히 기업 환경이나 규제가 엄격한 데이터를 다루는 사용자에게는 자신의 데이터가 로컬에 안전하게 유지되면서도 AI의 고급 기능을 활용할 수 있다는 점이 매우 중요하게 작용합니다.
초기 MCP 설정 방식은 CLI(명령줄 인터페이스) 마법사 방식이나 수동 JSON 파일 편집을 통해 이루어졌습니다. 그러나 이러한 방식들은 사용자들로부터 "설치가 너무 복잡하다"는 피드백을 받았습니다. 개발 도구 설치 필요, 수동 구성, 종속성 관리의 어려움, 유용한 서버를 찾기 위한 발견 메커니즘의 부재, 그리고 업데이트의 복잡성 등이 주요 장벽으로 작용했습니다.
MCP 설정 방법 1: Desktop Extensions (.dxt 파일) 활용 (권장)
이 섹션에서는 Claude Desktop에서 MCP 서버를 설정하는 가장 쉽고 권장되는 방법인 Desktop Extensions에 대해 자세히 설명합니다.
Desktop Extensions의 개념 및 장점
Desktop Extensions(.dxt 파일)는 전체 MCP 서버와 필요한 모든 종속성을 단일 설치 가능 패키지로 묶는 혁신적인 패키징 형식입니다.
Desktop Extensions의 주요 장점은 다음과 같습니다:
개발 도구 요구 사항 제거: 기존에는 Node.js나 Python과 같은 외부 개발 도구를 설치해야 했지만, Claude Desktop에 Node.js 런타임이 내장되어 있어 이러한 외부 종속성 설치가 필요 없어집니다.
5 자동 구성:
manifest.json파일 내의 정의를 통해 서버가 자동으로 구성되며, Claude Desktop이 이 모든 복잡성을 처리합니다.5 간소화된 종속성 관리: 모든 필수 패키지 및 라이브러리가
.dxt파일 내에 직접 번들로 제공되므로, 패키지 충돌이나 버전 불일치와 같은 호환성 문제가 방지됩니다.5 자동 업데이트: 확장 기능은 새 버전이 출시될 때 자동으로 업데이트되어, 사용자가 수동으로 재설치하거나 최신 상태를 유지하기 위한 부담을 덜어줍니다.
5 보안 비밀 관리: API 키와 같은 민감한 구성 정보는 운영 체제의 키체인에 안전하게 저장됩니다. Claude Desktop은 서버를 실행할 때 사용자 제공 값을 투명하게 대체하여 민감한 정보가 직접 노출되지 않도록 합니다.
5 사용자 친화적인 구성 UI: 만약 서버가 사용자 입력을 요구하는 경우, Claude Desktop은 직관적인 사용자 인터페이스를 표시하여 입력을 검증하고 민감한 값을 안전하게 저장합니다.
5
###.dxt 파일을 이용한 간편 설치 단계
.dxt 파일을 이용한 설치는 다음 세 가지 간단한 단계로 이루어집니다
.dxt파일 다운로드: 원하는 MCP 서버의.dxt파일을 다운로드합니다.Claude Desktop으로 열기: 다운로드한
.dxt파일을 더블 클릭하여 Claude Desktop으로 엽니다."설치(Install)" 클릭: Claude Desktop에 표시되는 설치 프롬프트에서 "설치" 버튼을 클릭합니다.
이 간소화된 과정은 사용자가 터미널을 사용하거나, 복잡한 구성 파일을 직접 편집하거나, 종속성 충돌을 해결할 필요를 없애줍니다.
이처럼.dxt 파일은 MCP 서버 설치를 '원클릭'으로 단순화하여
또한,.dxt는 민감한 데이터를 운영 체제 키체인에 안전하게 저장하고 자동 업데이트를 제공함으로써 보안을 강화합니다.
MCP 설정 방법 2: 수동 설정 (claude_desktop_config.json 편집)
이 섹션에서는 Claude Desktop에서 MCP 서버를 수동으로 구성하는 방법을 자세히 설명합니다. 이 방법은 Desktop Extensions보다 더 많은 제어 권한을 제공하며, 특정 요구 사항이나 사용자 정의 서버를 테스트하는 데 유용합니다.
수동 설정의 필요성 및 장점
Claude Code의 CLI 마법사 방식은 처음에는 사용자 친화적으로 보일 수 있지만, 오타가 발생하면 전체 과정을 다시 시작해야 하거나, 모든 구성을 한눈에 확인하기 어렵고, 복잡한 구성을 복사/붙여넣기 어려우며, 작은 수정에도 여러 프롬프트를 반복해야 하는 단점이 있습니다.
반면, claude_desktop_config.json 파일을 직접 편집하는 것은 다음과 같은 명확한 장점을 제공합니다
완전한 가시성: 모든 MCP 서버 구성을 한 화면에서 한 번에 확인하고 관리할 수 있습니다.
쉬운 복사 및 백업: 구성 파일을 쉽게 복사하여 다른 기기 간에 공유하거나 백업할 수 있습니다.
버전 관리: 구성 파일의 변경 사항을 시간 경과에 따라 추적하고 관리할 수 있어, 문제 발생 시 이전 버전으로 쉽게 되돌릴 수 있습니다.
이러한 장점들은 특히 복잡한 MCP 설정을 관리하거나, 자체 개발한 MCP 서버를 로컬에서 테스트하는 고급 사용자에게 매우 중요합니다.
claude_desktop_config.json 파일 위치 찾기
Claude Desktop의 MCP 설정 파일인 claude_desktop_config.json은 운영 체제에 따라 다음 경로에 저장됩니다.
운영 체제 | 파일 경로 |
macOS |
|
Windows |
|
이 파일은 Claude Desktop 애플리케이션 내에서 쉽게 찾거나 생성할 수 있습니다. Claude Desktop 메뉴에서 "설정(Settings…)"을 클릭한 다음, 왼쪽 사이드바에서 "개발자(Developer)"를 클릭하고 "구성 편집(Edit Config)" 버튼을 클릭하면 해당 파일이 열리거나, 존재하지 않을 경우 새로 생성됩니다.
Node.js 설치 확인
대부분의 MCP 서버는 Node.js 기반으로 실행되므로, 컴퓨터에 Node.js가 설치되어 있어야 합니다.
Windows + R 후 cmd 입력)을 열고 node -v 또는 npm -v를 입력합니다. 버전 정보가 올바르게 표시되면 Node.js가 설치되어 있는 것입니다.
만약 npx 명령이 실패하는 경우, 이는 NPM(Node Package Manager)이 전역으로 설치되어 있지 않을 수 있음을 의미합니다. Windows의 경우 %APPDATA%\npm 경로가 존재하는지 확인하고, 필요시 npm install -g npm 명령을 실행하여 NPM을 전역으로 설치해야 합니다.
설정 파일 직접 편집 가이드
claude_desktop_config.json 파일은 Claude Desktop이 시작될 때 어떤 MCP 서버를 시작할지 정의하는 핵심 파일입니다.
기본 구조 및 mcpServers 객체
모든 MCP 도구 구성은 JSON 파일 내의 mcpServers 객체 안에 포함되며, 각 도구는 고유한 이름으로 된 자체 항목을 가집니다.
예시: Filesystem MCP Server 추가
Filesystem MCP Server는 Claude가 사용자의 로컬 파일 시스템에 접근하고 수정할 수 있도록 하는 기본적인 서버입니다.
username은 실제 컴퓨터 사용자 이름으로 대체해야 하며, Claude가 접근할 수 있도록 하려는 유효한 디렉토리 경로를 지정해야 합니다.
JSON Configuration (macOS/Linux):
{
"mcpServers": {
"filesystem": {
"type": "stdio",
"command": "npx",
"args":
}
}
}
JSON Configuration (Windows):
{
"mcpServers": {
"type": "stdio",
"command": "npx",
"args":
}
}
예시: Sequential Thinking MCP Server 추가
Sequential Thinking MCP Server는 키나 경로를 사용하지 않는 가장 간단한 MCP 서버 중 하나입니다. 이 서버는 문제 해결을 위한 도구 사용을 안내하고 복잡한 문제를 관리 가능한 단계로 분해하는 데 도움을 줍니다.
JSON Configuration:
{
"mcpServers": {
"sequential-thinking": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-sequential-thinking"
]
}
}
}
예시: mcp-omnisearch (API 키 포함) 설정
mcp-omnisearch는 다양한 검색 도구를 통합하여 광범위한 기능을 제공하는 MCP 서버입니다. API 키는 선택 사항이며, 사용 가능한 키를 환경 변수로 설정하여 사용할 수 있습니다.
JSON Configuration:
{
"mcpServers": {
"mcp-omnisearch": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-omnisearch"
],
"env": {
"TAVILY_API_KEY": "your-tavily-key",
"BRAVE_API_KEY": "your-brave-key",
"KAGI_API_KEY": "your-kagi-key",
"PERPLEXITY_API_KEY": "your-perplexity-key",
"JINA_AI_API_KEY": "your-jina-key"
}
}
}
}
예시: 사용자 정의 MCP 도구 설정
자체 MCP 도구를 생성했거나 로컬에서 테스트하는 경우, 빌드된 JavaScript 파일을 직접 가리키도록 구성할 수 있습니다.
JSON Configuration:
{
"mcpServers": {
"my-custom-tool": {
"type": "stdio",
"command": "node",
"args": [
"/home/scott/mcp-tools/my-custom-tool/build/index.js"
]
}
}
}
Table: Common MCP Server Configuration Examples (JSON Snippets)
이 표는 일반적인 MCP 서버 및 사용자 정의 도구에 대한 실용적이고 바로 사용할 수 있는 JSON 코드 조각을 한데 모아 보여줍니다. 사용자는 이 구성을 쉽게 복사, 붙여넣기 및 수정할 수 있어 claude_desktop_config.json 파일을 수동으로 편집할 때의 노력과 구문 오류 가능성을 크게 줄일 수 있습니다. 또한, 다양한 유형의 MCP 서버에 대한 일반적인 구조와 매개변수를 명확하게 보여줍니다.
MCP 서버 유형 | 설명 | JSON 구성 예시 (일반적인 형식) |
Filesystem | Claude가 로컬 파일 시스템에 접근하고 수정할 수 있도록 합니다. (사용자 이름 및 경로를 실제 값으로 대체해야 합니다.) |
|
Sequential Thinking | 키나 경로를 사용하지 않는 가장 간단한 서버입니다. 문제 해결에 도구 사용을 안내합니다. |
|
mcp-omnisearch | 다양한 검색 도구를 통합합니다. (API 키는 선택 사항이며, 실제 키로 대체해야 합니다.) |
|
사용자 정의 MCP 도구 | 자체 개발한 MCP 도구를 로컬에서 실행하도록 구성합니다. (경로를 실제 빌드된 JavaScript 파일 경로로 대체해야 합니다.) |
|
변경 사항 적용을 위한 Claude Desktop 재시작
claude_desktop_config.json 파일을 편집한 후에는 변경 사항이 적용되도록 Claude Desktop 애플리케이션을 완전히 재시작해야 합니다.
MCP 설정 문제 해결 및 디버깅
MCP 서버 설정 과정에서 문제가 발생할 수 있습니다. 다음은 일반적인 문제 해결 단계와 디버깅 팁입니다.
일반적인 문제: 서버가 표시되지 않거나 도구 아이콘이 없는 경우
MCP 서버가 Claude Desktop에 올바르게 로드되지 않거나, 입력 상자 하단에 슬라이더 아이콘(도구 활성화 표시)이 나타나지 않는 경우, 다음 단계를 시도해 볼 수 있습니다
Claude Desktop 완전히 재시작: 사소한 오류를 해결하고 구성 변경 사항이 적용되도록 하려면 애플리케이션을 완전히 종료했다가 다시 시작하는 것이 좋습니다.
4 claude_desktop_config.json파일 구문 확인: JSON 파일의 구문이 올바른지 철저히 검토해야 합니다. 작은 오타나 쉼표 누락도 파일이 올바르게 파싱되지 않도록 막을 수 있습니다.4 파일 경로 유효성 및 절대 경로 확인:
claude_desktop_config.json에 포함된 모든 파일 경로는 유효해야 하며, 상대 경로가 아닌 절대 경로(예: Windows의C:\Users\username\Desktop또는 macOS의/Users/username/Desktop)여야 합니다.4
로그 파일 확인 방법 및 위치
로그 파일은 오류에 대한 중요한 정보를 제공하므로 문제 해결의 핵심 도구입니다.
macOS:
~/Library/Logs/ClaudeWindows:
%APPDATA%\Claude\Claude\logs
이 디렉토리에는 두 가지 주요 로그 파일 유형이 있습니다
mcp.log: MCP 연결 및 연결 실패에 대한 일반적인 로깅을 포함합니다.mcp-server-SERVERNAME.log: 특정 MCP 서버에서 발생하는 오류(stderr) 로깅을 포함합니다. 여기서SERVERNAME은 구성 파일에 정의된 서버의 이름입니다.
최근 로그를 확인하고 새로운 로그를 실시간으로 추적하려면 다음 명령을 사용할 수 있습니다
macOS/Linux:
tail -n 20 -f ~/Library/Logs/Claude/mcp\*.logWindows:
type "%APPDATA%\Claude\logs\mcp\*.log"(Windows에서는 최근 로그만 표시됩니다.)
명령줄에서 서버 수동 실행을 통한 문제 진단
MCP 서버 자체의 문제인지 Claude Desktop과의 통합 문제인지 확인하기 위해 명령줄에서 서버를 수동으로 실행해 볼 수 있습니다.
macOS/Linux 예시:
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/DownloadsWindows 예시: npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads
username을 실제 컴퓨터 사용자 이름으로 대체해야 합니다. 이 테스트를 통해 서버가 독립적으로 올바르게 빌드되고 실행되는지 확인할 수 있습니다.4
도구 호출 실패 시 대처법
Claude가 도구를 사용하려고 시도했지만 실패하는 경우, 다음을 확인해야 합니다
Claude 로그에서 오류 확인: 위에서 언급한
mcp.log및mcp-server-SERVERNAME.log파일을 검토하여 구체적인 오류 메시지를 찾습니다.4 서버 빌드 및 실행 확인: 사용자 정의 서버를 빌드하는 경우, Claude Desktop 외부에서 독립적으로 컴파일되고 오류 없이 실행되는지 확인합니다.
4 Claude Desktop 재시작: 때때로 재시작은 Claude와 서버 간의 임시 통신 문제를 해결할 수 있습니다.
4
ENOENT 오류 및 APPDATA 경로 문제 해결
서버 로그에서 ENOENT 오류, 특히 경로 내에 ${APPDATA}가 언급된 오류가 발생하는 경우, claude_desktop_config.json 파일의 env 키에 %APPDATA%의 확장된 값을 명시적으로 추가해야 할 수 있습니다.
예시:
{
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
"BRAVE_API_KEY": "..."
}
}
}
NPM 전역 설치 확인
npx 명령이 실패하는 것은 NPM(Node Package Manager)이 전역으로 설치되어 있지 않기 때문일 수 있습니다.
%APPDATA%\npm 경로가 존재하는지 확인하고, 그렇지 않다면 npm install -g npm 명령을 실행하여 NPM을 전역으로 설치해야 합니다.
결론 및 추가 활용 팁
Claude Desktop에서 Model Context Protocol (MCP)을 설정하는 방법은 크게 두 가지로 나뉩니다: 간편한 Desktop Extensions(.dxt 파일) 활용과 더 많은 제어 권한을 제공하는 수동 설정(claude_desktop_config.json 편집).
Desktop Extensions는 설치 과정을 획기적으로 단순화하여, 개발 도구 설치 없이 '원클릭'으로 MCP 서버를 배포하고 자동으로 업데이트하며 민감한 정보를 안전하게 관리할 수 있도록 합니다. 이는 Claude Desktop의 사용자 접근성을 크게 향상시키고, 더 넓은 사용자층이 MCP 기능을 쉽게 활용할 수 있도록 하여 MCP 생태계의 확장을 촉진합니다. 특히 기업 환경에서는 중앙 집중식 관리 및 보안 기능이 강화되어 Claude Desktop의 엔터프라이즈 도입을 용이하게 합니다.
반면, 수동 설정은 구성에 대한 완전한 가시성과 세밀한 제어를 제공하며, 백업 및 버전 관리에 용이합니다. 이는 사용자 정의 MCP 서버를 개발하거나 특정 환경에 맞춰 정교하게 조정해야 하는 고급 사용자에게 적합합니다. 이 방법은 Node.js 설치와 JSON 구문에 대한 이해를 요구하지만, 다양한 MCP 서버를 유연하게 통합할 수 있는 강력한 수단을 제공합니다.
사용자는 자신의 기술적 숙련도와 특정 요구 사항에 따라 두 가지 방법 중 하나를 선택할 수 있습니다. 대부분의 사용자에게는 Desktop Extensions가 권장되지만, 개발자나 특정 설정을 필요로 하는 경우에는 수동 설정이 필수적입니다.
MCP를 활용함으로써 Claude Desktop은 단순히 클라우드 기반의 AI를 넘어, 사용자의 로컬 환경과 긴밀하게 통합되는 강력한 '로컬 인텔리전스'를 갖추게 됩니다. 이는 데이터 프라이버시를 유지하면서 개인화되고 효율적인 작업을 가능하게 합니다. MCP는 Claude의 잠재력을 극대화하고, 파일 시스템 접근부터 복잡한 검색 도구 통합, 그리고 사용자 정의 솔루션에 이르기까지 무한한 확장 가능성을 열어줍니다.
더 많은 MCP 서버를 탐색하고자 한다면, Smithery나 Glama와 같은 MCP 저장소를 찾아보는 것이 유용할 수 있습니다.
0 댓글