MCP(Model Context Protocol)를 설정하면 Claude가 단순한 챗봇을 넘어 파일 시스템, GitHub, 데이터베이스, 웹 검색 등 외부 도구와 직접 연결되는 강력한 AI 에이전트로 변신합니다. 이 글에서는 Claude Desktop과 Claude Code 두 환경에서 MCP를 처음부터 끝까지 설정하는 방법을 단계별로 안내합니다. 설정 파일 경로, JSON 구성 방법, 인기 MCP 서버 추천, 그리고 실제 트러블슈팅 사례까지 모두 다루니, 이 가이드 하나로 MCP 연동을 완료할 수 있습니다.
“Claude에게 GitHub 이슈를 정리해달라고 하고 싶은데, 어떻게 연결하지?” “MCP가 좋다는데 설정이 어렵다던데?” 이런 고민을 가진 분이라면 정확히 맞는 글입니다. 개발자가 아니더라도 따라 할 수 있도록 모든 과정을 구체적으로 설명하겠습니다.
MCP란 무엇이고, 왜 필요한가
MCP는 AI 모델이 외부 도구와 데이터 소스에 표준화된 방식으로 접근할 수 있게 해주는 개방형 프로토콜입니다. Anthropic이 2024년에 공개했으며, 흔히 “AI를 위한 USB-C 포트”에 비유됩니다. 하나의 표준 인터페이스로 다양한 서비스를 연결할 수 있다는 뜻입니다.
MCP 이전에는 AI에게 파일을 분석시키려면 직접 내용을 복사해서 붙여넣어야 했습니다. GitHub 이슈를 확인하려면 웹사이트에서 일일이 복사해와야 했고, 데이터베이스 쿼리 결과를 분석하려면 수작업이 필수였습니다. MCP를 연결하면 이런 과정이 전부 자동화됩니다.
MCP의 클라이언트-서버 구조
MCP는 클라이언트와 서버로 구성됩니다. 클라이언트는 Claude Desktop이나 Claude Code 같은 AI 앱이고, 서버는 특정 기능을 제공하는 프로그램입니다. 예를 들어 파일 시스템 MCP 서버는 로컬 폴더의 파일을 읽고 쓰는 기능을, GitHub MCP 서버는 저장소 관리 기능을 제공합니다. 서버는 로컬 컴퓨터에서 자식 프로세스로 실행되므로 네트워크에 노출되지 않아 보안 측면에서도 안전합니다.
2026년 3월 현재, MCP 마켓플레이스에는 수천 개의 서버가 등록되어 있으며, Smithery, MCP Market, LobeHub 등의 플랫폼에서 검색하고 설치할 수 있습니다. GitHub, Slack, Notion, Figma, PostgreSQL, MongoDB, Brave Search 등 주요 서비스 대부분을 MCP로 연결할 수 있습니다.
MCP 설정 전 준비사항
MCP를 사용하려면 반드시 Node.js가 설치되어 있어야 합니다. 대부분의 MCP 서버가 npx 명령어로 실행되기 때문입니다. 아래 순서대로 준비하세요.
Node.js 설치 확인
터미널(맥) 또는 명령 프롬프트(윈도우)를 열고 다음 명령어를 입력합니다.
node --version
npm --version
버전 번호가 출력되면 이미 설치된 것입니다. Node.js 20 이상을 권장합니다. 설치되어 있지 않다면 nodejs.org에서 LTS 버전을 다운로드하여 설치합니다. macOS 사용자는 Homebrew로 brew install node 명령을 사용해도 됩니다.
Claude Desktop 또는 Claude Code 설치
Claude Desktop은 claude.ai/download에서 운영체제에 맞는 버전을 다운로드합니다. Claude Code는 터미널에서 npm install -g @anthropic-ai/claude-code 명령으로 설치합니다. 두 환경의 MCP 설정 방식이 다르므로, 사용하는 환경에 맞는 섹션을 참고하세요.
Claude Desktop에서 MCP 설정하는 법
Claude Desktop에서 MCP를 설정하는 핵심은 claude_desktop_config.json이라는 설정 파일을 편집하는 것입니다. 이 파일 하나에 사용할 MCP 서버 정보를 JSON 형식으로 작성하면 됩니다.
1단계: 설정 파일 찾기
설정 파일의 위치는 운영체제마다 다릅니다.
macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json 경로에 있습니다. Windows의 경우 %APPDATA%\Claude\claude_desktop_config.json 경로를 사용합니다.
가장 쉬운 방법은 Claude Desktop 앱에서 직접 여는 것입니다. 설정(Settings) → 개발자(Developer) → 설정 편집(Edit Config) 버튼을 클릭하면 해당 파일이 열립니다. 파일이 없으면 자동으로 생성됩니다.
2단계: MCP 서버 추가하기
설정 파일을 열면 비어 있거나 기본 내용만 있을 수 있습니다. 다음과 같이 mcpServers 항목 아래에 원하는 서버를 추가합니다. 가장 기본적인 파일 시스템 서버 예시입니다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"],
"env": {}
}
}
}
각 항목의 의미는 다음과 같습니다. command는 실행할 명령어(보통 npx 또는 uvx), args는 명령어에 전달할 인자(서버 패키지명과 접근 경로), env는 API 키 같은 환경 변수입니다. 위 예시에서 /Users/username/Documents 부분은 Claude가 접근할 수 있는 폴더 경로이므로 본인 환경에 맞게 수정해야 합니다.
3단계: 여러 서버 동시 등록
여러 MCP 서버를 동시에 사용하고 싶다면 mcpServers 객체 안에 쉼표로 구분하여 추가합니다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/username/Documents"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_여기에토큰입력"
}
}
}
}
4단계: 재시작 및 확인
설정 파일을 저장한 후 Claude Desktop을 완전히 종료했다가 다시 실행합니다. 단순히 창을 닫는 것이 아니라, macOS에서는 Dock 아이콘을 우클릭하여 종료(Quit)를, Windows에서는 시스템 트레이 아이콘을 우클릭하여 종료(Exit)해야 합니다.
재시작 후 대화 입력창 근처에 망치 아이콘(🔨)이 나타나면 MCP 서버가 정상적으로 연결된 것입니다. 아이콘을 클릭하면 사용 가능한 도구 목록을 확인할 수 있습니다.
Windows 사용자 주의사항
Windows에서 npx를 사용하는 MCP 서버는 반드시 cmd /c 래퍼를 사용해야 합니다. 그렇지 않으면 “Connection closed” 오류가 발생합니다. 설정 예시는 다음과 같습니다.
{
"mcpServers": {
"filesystem": {
"command": "cmd",
"args": ["/c", "npx", "-y", "@modelcontextprotocol/server-filesystem", "C:\\Users\\username\\Documents"]
}
}
}
3. Claude Code에서 MCP 설정하는 법
Claude Code에서는 CLI 명령어 또는 프로젝트 설정 파일을 통해 MCP를 구성합니다. Claude Desktop과 달리 JSON 파일을 직접 편집하지 않아도 되는 편리한 방법이 제공됩니다.
CLI 명령어로 MCP 서버 추가
터미널에서 claude mcp add 명령을 사용하면 MCP 서버를 간단히 추가할 수 있습니다.
claude mcp add github -- npx -y @modelcontextprotocol/server-github
환경 변수가 필요한 경우 --env 플래그를 사용합니다.
claude mcp add github --env GITHUB_TOKEN=ghp_토큰값 -- npx -y @modelcontextprotocol/server-github
추가된 서버를 확인하려면 claude mcp list, 특정 서버의 상세 정보를 보려면 claude mcp get 서버이름, 삭제하려면 claude mcp remove 서버이름 명령을 사용합니다.
MCP 서버의 세 가지 범위
Claude Code에서 MCP 서버는 세 가지 범위(scope)로 설정할 수 있으며, 각 범위에 따라 접근 가능한 범위가 달라집니다.
local(기본값)은 현재 프로젝트에서 본인만 사용할 수 있는 범위입니다. 개인 개발 서버나 민감한 자격 증명이 포함된 서버에 적합합니다. project는 프로젝트 루트의 .mcp.json 파일을 통해 팀 전체가 공유하는 범위입니다. 팀 공용 서버 설정에 사용합니다. user는 모든 프로젝트에서 본인이 사용할 수 있는 전역 범위입니다. 범위를 지정하려면 -s 플래그를 사용합니다.
claude mcp add github -s user -- npx -y @modelcontextprotocol/server-github
.mcp.json 파일로 팀 공유 설정
팀원들과 MCP 설정을 공유하려면 프로젝트 루트에 .mcp.json 파일을 생성합니다. 이 파일은 Git으로 버전 관리할 수 있어 팀 전체가 동일한 MCP 환경을 사용할 수 있습니다.
{
"mcpServers": {
"context7": {
"command": "npx",
"args": ["-y", "@upstash/context7-mcp"]
},
"playwright": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-server-playwright"]
}
}
}
Claude Code 내부에서 MCP 상태 확인
Claude Code 대화 중에 /mcp 명령을 입력하면 현재 연결된 MCP 서버의 상태를 확인할 수 있습니다. 문제가 있을 때는 /doctor 명령으로 진단을 실행할 수도 있습니다.
MCP 설정을 변경한 후에는 Claude Code를 재시작해야 합니다. /exit으로 종료한 후 다시 claude 명령으로 시작하면 됩니다. 이전 세션을 이어가고 싶다면 claude --continue 옵션을 사용하세요.
꼭 알아야 할 인기 MCP 서버 추천
2026년 현재 가장 많이 사용되는 MCP 서버들을 용도별로 정리했습니다. 처음 시작한다면 파일 시스템 서버부터 연결해보고, 필요에 따라 하나씩 추가하는 것을 권장합니다.
개발 생산성 서버
GitHub MCP 서버는 이슈 생성, PR 관리, 코드 검색 등 GitHub의 핵심 기능을 Claude에서 직접 수행할 수 있게 합니다. Context7 MCP 서버는 라이브러리의 최신 버전별 문서와 코드 예제를 실시간으로 제공하여 코딩 작업의 정확도를 높여줍니다. Playwright MCP 서버는 브라우저 자동화를 지원하여 웹 페이지 탐색, 클릭, 텍스트 입력 등을 AI가 직접 수행할 수 있습니다.
데이터 및 생산성 서버
PostgreSQL MCP 서버는 데이터베이스 쿼리 실행, 인덱스 튜닝, 상태 점검 등을 지원합니다. Notion MCP 서버는 노션 문서의 읽기, 쓰기, 검색이 가능하며 지식 관리 자동화에 유용합니다. Slack MCP 서버는 채널 메시지 읽기, 검색, 전송을 AI를 통해 처리할 수 있게 합니다. Brave Search MCP 서버는 Claude에게 실시간 웹 검색 능력을 부여합니다.
MCP 서버 검색 플랫폼
새로운 MCP 서버를 찾으려면 Smithery(smithery.ai), MCP Market(mcpmarket.com), LobeHub MCP 디렉토리 등의 플랫폼을 활용하세요. 각 서버의 설치 명령어와 설정 파일 예시를 바로 확인할 수 있어 편리합니다.
MCP 설정 시 자주 발생하는 오류와 해결법
MCP 설정에서 가장 흔한 문제는 JSON 구문 오류, 경로 문제, Node.js 버전 불일치입니다. 아래에서 각 문제별 해결 방법을 안내합니다.
JSON 구문 오류
설정 파일의 쉼표 누락, 괄호 불일치, 따옴표 오류는 모든 서버를 무력화시킵니다. 터미널에서 다음 명령으로 JSON 유효성을 검증할 수 있습니다.
cat claude_desktop_config.json | python3 -m json.tool
특히 마지막 항목 뒤에 쉼표를 넣는 실수(trailing comma)가 자주 발생합니다. JSON 표준에서는 마지막 항목 뒤에 쉼표를 허용하지 않으므로 반드시 제거하세요.
서버 연결 안 됨
서버가 연결되지 않을 때 확인할 사항은 다음과 같습니다. 먼저, 설정 파일 경로가 정확한지 확인합니다. macOS에서는 ~/Library/Application Support/Claude/ 폴더에 파일이 있어야 합니다. 다음으로, npx가 정상 작동하는지 터미널에서 npx -y @modelcontextprotocol/server-filesystem 명령을 직접 실행해봅니다. Node.js가 설치되지 않았거나 PATH에 등록되지 않았다면 이 단계에서 오류가 발생합니다.
로그 확인 방법
문제 원인을 파악하려면 로그 파일을 확인합니다. macOS에서는 tail -f ~/Library/Logs/Claude/mcp*.log 명령으로 실시간 로그를 볼 수 있습니다. Windows에서는 %APPDATA%\Claude\Logs\ 폴더에서 로그 파일을 확인합니다.
타임아웃 설정
MCP 서버 시작에 시간이 오래 걸리는 경우 타임아웃 값을 조정할 수 있습니다. Claude Code에서는 MCP_TIMEOUT=10000 claude 명령으로 10초 타임아웃을 설정합니다. 대용량 데이터를 처리하는 서버라면 MAX_MCP_OUTPUT_TOKENS=50000 환경 변수로 출력 토큰 제한도 늘릴 수 있습니다.
MCP 실전 활용 사례
MCP를 실제 업무에 활용하면 기존에 수시간 걸리던 작업을 몇 분 안에 처리할 수 있습니다. IMWEB 인프라팀의 사례에 따르면, Datadog MCP와 Slack MCP를 함께 사용하여 50개의 모니터링 임계값을 일괄 업데이트하는 작업을 수동 4~5시간에서 3분으로 단축했습니다.
개발 워크플로우 자동화
GitHub MCP를 연결하면 “이번 주 생성된 이슈 중 버그 라벨이 붙은 것을 정리해줘”라는 자연어 요청만으로 이슈 현황을 파악할 수 있습니다. PR 리뷰 요약, 브랜치 비교, 코드 검색까지 대화형으로 처리 가능합니다.
파일 분석 및 관리
파일 시스템 MCP를 연결하면 “Documents 폴더에서 지난 3개월 내 수정된 PDF를 찾아줘”같은 복잡한 파일 검색을 AI에게 맡길 수 있습니다. 여러 파일의 내용을 한꺼번에 분석하거나 요약하는 작업도 자동화됩니다.
멀티 MCP 연계
진정한 힘은 여러 MCP를 조합할 때 나옵니다. AWS MCP로 인프라 상태를 확인하고, Datadog MCP로 모니터링 데이터를 분석한 뒤, Slack MCP로 결과를 팀 채널에 공유하는 전체 워크플로우를 하나의 대화에서 처리할 수 있습니다. 이런 방식으로 운영 업무의 자동화 수준을 비약적으로 높일 수 있습니다.
보안 주의사항과 베스트 프랙티스
MCP는 Claude에게 실제 시스템 접근 권한을 부여하므로 보안에 각별히 신경 써야 합니다.
파일 시스템 서버를 설정할 때는 접근이 필요한 폴더만 최소한으로 지정하세요. SSH 키, .env 파일, 자격 증명이 저장된 폴더는 절대 허용 경로에 포함하지 않아야 합니다. API 키는 설정 파일에 직접 하드코딩하지 말고 환경 변수로 관리하는 것이 안전합니다.
팀용 .mcp.json 파일에는 API 키를 포함하지 않도록 주의하세요. Git 저장소에 올라가면 키가 노출될 수 있습니다. 각 팀원이 자신의 환경 변수로 키를 설정하는 방식이 권장됩니다.
처음 MCP를 사용한다면 작은 테스트 프로젝트부터 시작하세요. 전용 스크래치 디렉토리를 만들어 파일 시스템 서버를 연결하고, 읽기·쓰기 동작이 어떻게 이루어지는지 충분히 익힌 후 실제 프로젝트에 적용하는 것이 안전합니다.
자주 묻는 질문 (FAQ)
MCP를 사용하려면 Claude 유료 구독이 필요한가요?
Claude Desktop에서 MCP 기능은 무료·유료 플랜 모두에서 사용할 수 있습니다. 다만 Claude Code는 별도의 API 사용료 또는 Claude 구독이 필요합니다. MCP 자체는 오픈 프로토콜이므로 프로토콜 사용에 따른 추가 비용은 없습니다.
MCP 설정을 변경하면 매번 재시작해야 하나요?
Claude Desktop은 설정 파일 변경 후 반드시 완전 종료 후 재시작해야 합니다. 단순히 창을 닫는 것이 아니라 프로세스를 완전히 종료해야 새 설정이 반영됩니다. Claude Code도 마찬가지로 /exit 후 재시작이 필요하며, --continue 옵션으로 이전 대화를 이어갈 수 있습니다.
여러 MCP 서버를 동시에 실행할 수 있나요?
네, mcpServers 객체 안에 여러 서버를 등록하면 Claude가 시작할 때 모든 서버를 동시에 실행합니다. 각 서버는 독립적인 프로세스로 작동하므로 하나의 서버에 문제가 생겨도 다른 서버에는 영향을 주지 않습니다.
macOS와 Windows에서 설정 방법이 다른가요?
기본 JSON 구조는 동일하지만, 설정 파일 경로와 Windows의 cmd /c 래퍼 요구사항이 다릅니다. Windows에서 npx를 사용하는 서버는 command를 “cmd”로 설정하고 args에 “/c”를 추가해야 정상 작동합니다. 경로 구분자도 Windows에서는 백슬래시(\)를 사용해야 합니다.
MCP 서버가 내 데이터를 외부로 전송하나요?
대부분의 MCP 서버는 로컬에서 자식 프로세스로 실행되며 외부 네트워크에 노출되지 않습니다. 파일 시스템 서버의 경우 사용자가 지정한 경로 내에서만 동작하며, 허용된 경로 밖의 요청은 거부합니다. 단, 원격 API를 호출하는 서버(GitHub, Slack 등)는 해당 서비스로 데이터가 전송되므로 각 서비스의 개인정보 정책을 확인하세요.
지금 바로 MCP를 시작하세요
MCP 설정은 처음 한 번만 해두면 이후 Claude를 사용하는 방식이 근본적으로 달라집니다. 핵심을 다시 정리하면, Claude Desktop은 claude_desktop_config.json 파일에 서버 정보를 JSON으로 작성하고, Claude Code는 claude mcp add 명령 또는 .mcp.json 파일을 사용합니다.
시작이 어렵게 느껴진다면 파일 시스템 서버 하나만 먼저 연결해보세요. Node.js를 설치하고, 설정 파일에 서버 한 줄을 추가하고, Claude를 재시작하면 됩니다. 망치 아이콘이 나타나는 순간, AI 비서가 진짜 비서처럼 일하기 시작합니다. 이 글에서 소개한 설정 파일 예시를 그대로 복사하여 본인 환경에 맞게 경로만 수정하면 5분 안에 첫 MCP 연결을 완료할 수 있습니다.