Claude Code에서 MCP(Model Context Protocol)를 설정하면 AI 어시스턴트가 외부 도구, 데이터베이스, API 등에 직접 접근할 수 있게 돼요. 단순한 텍스트 생성에 그치지 않고, 실제 환경과 상호작용하는 강력한 AI 워크플로우를 구축할 수 있어요.
이 글에서는 Claude Code에 MCP 서버를 설치하고 설정하는 전체 과정을 단계별로 정리해 드릴게요. macOS 기준으로 설명하지만, Windows와 Linux에서도 거의 동일하게 적용할 수 있어요.
MCP란 무엇인가요?
Model Context Protocol 개요
MCP(Model Context Protocol)는 Anthropic이 개발한 오픈 표준 프로토콜이에요. AI 모델이 외부 데이터 소스와 도구에 표준화된 방식으로 연결될 수 있도록 설계됐어요. 쉽게 말해, Claude가 파일 시스템을 읽거나, 데이터베이스를 조회하거나, 외부 API를 호출할 수 있게 해주는 ‘다리’ 역할이에요.
MCP로 무엇을 할 수 있나요?
MCP를 활용하면 Claude Code의 기능이 크게 확장돼요.
- 파일 시스템 접근: 로컬 파일 읽기·쓰기·검색
- 데이터베이스 연결: SQLite, PostgreSQL, MySQL 등 직접 쿼리
- 웹 검색: 실시간 정보 검색 및 크롤링
- 외부 API: GitHub, Slack, Notion 등 서드파티 서비스 연동
- 코드 실행: 격리된 환경에서 코드 실행 및 결과 반환
MCP 서버의 구조
MCP는 클라이언트-서버 구조로 동작해요. Claude Code가 클라이언트 역할을 하고, MCP 서버는 실제 도구와 데이터를 제공하는 역할을 해요. 서버는 로컬에서 실행되거나 원격에서 실행될 수 있고, stdio(표준 입출력)나 SSE(Server-Sent Events) 방식으로 통신해요.
설치 전 준비사항
시스템 요구사항
Claude Code MCP를 설치하기 전에 아래 환경이 준비돼 있는지 확인하세요.
- Claude Code CLI 최신 버전 설치 (npm install -g @anthropic-ai/claude-code)
- Node.js 18 이상 또는 Python 3.10 이상 (사용하는 MCP 서버 종류에 따라 다름)
- Anthropic API 키 보유 및 환경 변수 설정 완료
- 인터넷 연결 (서버 패키지 다운로드 및 API 통신)
Claude Code 설치 확인
터미널에서 아래 명령어로 Claude Code가 제대로 설치돼 있는지 확인할 수 있어요.
claude --version버전 번호가 출력되면 설치가 완료된 거예요. 설치가 안 돼 있다면 npm을 통해 먼저 설치하세요.
MCP 서버 설치하기
공식 MCP 서버 목록 확인
Anthropic과 커뮤니티가 제공하는 공식 MCP 서버는 GitHub의 modelcontextprotocol/servers 리포지토리에서 확인할 수 있어요. 파일 시스템, 데이터베이스, 웹 검색, GitHub 연동 등 다양한 서버가 준비돼 있어요.
npm 기반 MCP 서버 설치 예시
가장 많이 사용하는 파일시스템 MCP 서버를 설치해 볼게요. 터미널에서 아래 명령어를 실행하세요.
npm install -g @modelcontextprotocol/server-filesystem설치 완료 후 mcp-server-filesystem --version 명령어로 정상 설치 여부를 확인하세요.
Python 기반 MCP 서버 설치 예시
Python으로 작성된 MCP 서버는 pip 또는 uv를 사용해 설치해요.
pip install mcp-server-sqlite또는 uv를 사용한다면:
uv tool install mcp-server-sqliteClaude Code에 MCP 설정하기
설정 파일 위치
Claude Code의 MCP 설정은 JSON 형식의 설정 파일에서 관리해요. 설정 파일의 기본 위치는 아래와 같아요.
- macOS/Linux:
~/.claude/settings.json또는 프로젝트 루트의.claude/settings.json - Windows:
%APPDATA%\Claude\settings.json
설정 파일 작성 예시
설정 파일에 MCP 서버 정보를 추가하는 방법이에요. 파일시스템 서버를 예시로 볼게요.
{
"mcpServers": {
"filesystem": {
"command": "mcp-server-filesystem",
"args": ["/Users/yourname/projects"],
"env": {}
}
}
}여기서 args에 접근을 허용할 디렉터리 경로를 지정해요. 여러 경로를 허용하려면 배열에 추가하면 돼요.
Claude Code CLI로 MCP 서버 추가하기
설정 파일을 직접 편집하는 대신 CLI 명령어로 MCP 서버를 추가할 수도 있어요.
claude mcp add filesystem mcp-server-filesystem /Users/yourname/projects이 명령어 한 줄로 설정 파일에 자동으로 서버 정보가 추가돼요. 설정이 잘 됐는지 확인하려면 아래 명령어를 실행하세요.
claude mcp listMCP 서버 연결 확인 및 테스트
Claude Code 실행 후 MCP 상태 확인
Claude Code를 실행하면 설정된 MCP 서버가 자동으로 연결돼요. 세션 시작 시 터미널에 연결된 MCP 서버 목록이 표시되는데, 서버 이름 옆에 초록색 체크 표시나 ‘connected’ 메시지가 뜨면 정상이에요.
도구 사용 테스트
Claude Code 세션 안에서 파일 시스템 MCP 서버가 연결됐다면, “내 프로젝트 폴더의 파일 목록을 보여줘”라고 입력해 보세요. Claude가 실제로 지정한 디렉터리를 조회해 파일 목록을 반환해 준다면 MCP가 정상 작동하는 거예요.
자주 발생하는 오류와 해결 방법
서버 연결 실패 (Connection Error)
MCP 서버가 연결되지 않는 경우 가장 먼저 확인할 사항이에요.
- 서버 패키지가 제대로 설치됐는지 확인 (명령어 재실행)
- 설정 파일의
command필드가 올바른 실행 파일 이름을 가리키는지 확인 - 지정한 경로가 실제로 존재하는지 확인
- macOS에서 권한 문제라면
chmod +x로 실행 권한 부여
설정 파일 JSON 오류
설정 파일에 문법 오류가 있으면 Claude Code 시작 시 에러가 발생해요. JSON 문법 오류를 방지하려면 쉼표(,) 위치와 중괄호 매칭을 꼼꼼히 확인하세요. VS Code나 텍스트 에디터의 JSON 유효성 검사 기능을 활용하면 편해요.
권한(Permission) 관련 오류
파일 시스템 MCP 서버에서 접근 거부 오류가 나는 경우, Claude Code 설정에서 해당 경로에 대한 접근 권한이 허용돼 있는지 확인하세요. .claude/settings.json의 permissions 섹션에 필요한 경로와 작업을 추가해야 해요.
유용한 MCP 서버 추천
처음 MCP를 설정하는 분께 유용한 서버 목록을 정리해 드릴게요.
- filesystem: 로컬 파일 읽기·쓰기, 가장 기본적인 서버
- github: GitHub 리포지토리 접근, 이슈·PR 관리
- sqlite: SQLite 데이터베이스 직접 쿼리
- brave-search: Brave 검색 API를 통한 실시간 웹 검색
- slack: Slack 채널 읽기·메시지 발송
- puppeteer: 웹 브라우저 자동화 및 스크린샷
Claude Code에 MCP를 설정하면 AI 어시스턴트의 능력이 단순한 텍스트 생성을 넘어 실제 개발 환경과 연동되는 수준으로 높아져요. 처음에는 파일시스템 서버 하나부터 시작해서 필요에 따라 서버를 추가해 가는 방식으로 익혀가길 권해요. MCP 생태계는 빠르게 성장 중이라 새로운 서버도 계속 추가되고 있으니, 공식 GitHub 리포지토리를 즐겨찾기 해두면 유용할 거예요.