지난 글에서 MCP 서버가 무엇인지, AI와 외부 도구를 연결하는 통역사 역할을 한다는 개념을 살펴봤습니다. 이번 글은 그 후속편입니다. 실제로 Claude Code에서 MCP 서버를 어떻게 연결하는지, 설정 파일은 어디에 두는지, 어떤 서버가 자주 쓰이는지를 구체적으로 정리해봤어요.
MCP 개념이 아직 낯설다면 MCP 서버란? AI가 외부 도구와 연결되는 방법을 먼저 읽고 오시면 이해가 훨씬 빠를 겁니다.
MCP가 뭔가요? (간단 복습)
MCP(Model Context Protocol)는 AI가 외부 도구나 데이터에 접근할 때 사용하는 표준 프로토콜입니다. 쉽게 말해, Claude가 직접 파일을 읽거나 데이터베이스를 조회하거나 브라우저를 제어하려면 어떤 “중간 다리”가 필요한데, 그 다리 역할을 하는 게 MCP 서버예요.
포인트는 표준화에 있어요. USB-C처럼, 한 번 만든 MCP 서버는 MCP를 지원하는 어떤 AI 도구에서도 재사용할 수 있습니다. Claude Code가 MCP를 공식 지원하는 덕분에, 설정 파일 몇 줄만 추가하면 Claude가 실제 업무 도구와 연결됩니다.
Claude Code에서 MCP 연결하는 법
Claude Code는 두 곳에서 MCP 서버 설정을 읽습니다. 어디에 두느냐에 따라 적용 범위가 달라져요.
설정 파일 위치
.claude/settings.json— 프로젝트 단위 설정. 해당 프로젝트 폴더에서만 적용됩니다. 팀원과 공유하거나, 프로젝트마다 다른 MCP 서버를 쓸 때 유용해요.~/.claude/settings.json(사용자 홈 디렉토리) — 전역 설정. 모든 프로젝트에서 공통으로 사용하는 MCP 서버를 여기에 두면 됩니다.
일부 가이드에서 .mcp.json 파일을 언급하기도 하는데, Claude Code의 공식 설정은 settings.json 안의 mcpServers 키를 사용하는 방식이 일반적입니다.
기본 설정 형식
설정 파일에 mcpServers 키를 추가하고, 그 안에 서버 이름과 실행 방법을 정의합니다.
{
"mcpServers": {
"서버이름": {
"command": "실행할 명령어",
"args": ["인자1", "인자2"],
"env": {
"API_KEY": "토큰값"
}
}
}
}- command: MCP 서버를 실행하는 명령어 (주로
npx또는python) - args: 명령어에 넘길 인자 배열
- env: 서버에 필요한 환경변수 (API 키 등)
연결 상태 확인
Claude Code 터미널에서 /mcp 명령을 입력하면 현재 연결된 MCP 서버 목록과 상태를 확인할 수 있어요. 연결이 잘 됐으면 서버 이름 옆에 녹색 표시가 뜨고, 문제가 있으면 오류 메시지가 나옵니다.
실전 예시 — 자주 쓰는 MCP 서버 5가지
공개된 MCP 서버 중 실무에서 많이 사용되는 5가지를 설정 예시와 함께 정리했습니다.
1. filesystem — 로컬 파일 읽기/쓰기
지정한 폴더 안의 파일을 Claude가 직접 읽고 쓸 수 있게 해줍니다. “문서 폴더에서 지난달 보고서 찾아줘” 같은 요청이 실제로 동작해요.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Documents"]
}
}
}경로 부분(/Users/username/Documents)은 접근을 허용할 실제 폴더로 바꾸면 됩니다. 여러 폴더를 열어줄 수도 있어요.
2. github — 리포지토리 조회 및 PR 관리
GitHub 리포지토리의 이슈, PR, 코드를 조회하고 댓글을 달거나 이슈를 생성할 수 있습니다. 코드 리뷰나 이슈 트래킹을 Claude와 함께할 때 유용해요.
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token_here"
}
}
}
}GitHub 개인 액세스 토큰은 GitHub 설정의 Developer settings에서 발급받을 수 있습니다.
3. postgres — 데이터베이스 조회
PostgreSQL 데이터베이스에 연결해 자연어로 데이터를 조회합니다. SQL을 몰라도 “지난달 매출 상위 10건 보여줘”라고 하면 쿼리를 짜서 결과를 가져옵니다.
{
"mcpServers": {
"postgres": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-postgres",
"postgresql://username:password@localhost:5432/dbname"
]
}
}
}4. brave-search — 웹 검색
Brave Search API를 통해 Claude가 실시간 웹 검색을 수행합니다. 최신 정보가 필요한 질문에 특히 유용해요. Brave Search API 키가 필요합니다.
{
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "your_brave_api_key"
}
}
}
}5. puppeteer — 브라우저 제어
Chromium 브라우저를 자동으로 띄워서 웹페이지를 열거나, 스크린샷을 찍거나, 클릭·입력 같은 조작을 수행합니다. 웹 스크래핑이나 자동화 테스트에 쓸 수 있어요.
{
"mcpServers": {
"puppeteer": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-puppeteer"]
}
}
}puppeteer 서버는 별도 API 키 없이 바로 사용할 수 있습니다. 단, Chromium이 로컬에 설치되어 있어야 해요.
설정 파일 구조 이해하기
여러 MCP 서버를 동시에 연결할 수 있습니다. mcpServers 안에 서버 이름을 키로 해서 여러 개를 나란히 두면 됩니다.
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@anthropic-ai/mcp-filesystem", "/Users/username/Documents"]
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_your_token"
}
},
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "your_key"
}
}
}
}각 서버는 독립적으로 실행됩니다. filesystem 서버가 문제가 생겨도 github 서버는 정상 동작하는 식이에요. 서버 이름은 직관적으로 지으면 되고, 나중에 /mcp 명령어로 확인할 때 이 이름으로 표시됩니다.
보안 관련 주의사항
MCP 서버는 기본적으로 로컬에서 실행됩니다. 즉, Claude가 MCP를 통해 파일을 읽거나 DB에 접근할 때, 그 요청은 클라우드 서버가 아니라 내 컴퓨터에서 처리됩니다. 이 점에서 데이터가 외부로 나가지 않는다는 장점이 있지만, 반대로 다음 사항을 주의해야 해요.
- filesystem 경로는 필요한 범위만 열어주세요. 루트 디렉토리 전체를 허용하면 Claude가 시스템 파일에도 접근할 수 있게 됩니다.
- API 키는 설정 파일에 직접 쓰지 않는 게 좋아요. 환경변수로 별도 관리하거나,
.env파일에 두고 설정 파일에서 참조하는 방식이 더 안전합니다. - 출처가 불분명한 MCP 서버는 쓰지 마세요. Anthropic 공식 서버나 GitHub에서 활발히 관리되는 공개 서버를 선택하는 게 기본이에요.
트러블슈팅 — 연결 안 될 때
MCP 서버가 예상대로 연결이 안 될 때 확인해볼 체크리스트입니다.
1. Node.js가 설치되어 있는지 확인
대부분의 MCP 서버는 npx로 실행합니다. npx는 Node.js에 포함된 도구이므로, Node.js가 없으면 서버 자체가 실행되지 않아요. 터미널에서 node -v를 입력해서 버전이 뜨는지 확인해보세요. 없으면 nodejs.org에서 LTS 버전을 받으면 됩니다.
2. JSON 문법 오류 점검
설정 파일이 JSON 형식이라 쉼표 하나, 따옴표 하나가 틀려도 전체가 읽히지 않아요. VSCode나 온라인 JSON 검증 도구(jsonlint.com 등)에 붙여넣어서 오류가 없는지 확인해보세요.
3. /mcp 명령으로 상태 확인
Claude Code 터미널에서 /mcp를 입력하면 현재 등록된 서버 목록과 상태가 나옵니다. “연결 실패” 메시지가 있다면 어떤 서버에서 어떤 오류가 났는지 확인할 수 있어요.
4. API 키나 권한 문제
GitHub, Brave Search처럼 API 키가 필요한 서버라면, 키 값이 맞는지, 해당 키에 필요한 권한이 부여되어 있는지 확인하세요. GitHub 토큰의 경우 리포지토리 읽기 권한이 없으면 조회가 안 됩니다.
5. Claude Code 재시작
설정 파일을 수정한 뒤에는 Claude Code를 완전히 종료하고 다시 시작해야 반영됩니다. 변경사항이 바로 적용되지 않는 것처럼 보인다면 재시작이 해결책인 경우가 많아요.
6. 패키지 버전 문제
npx -y는 실행 시점에 최신 버전을 다운로드합니다. 간혹 최신 버전에서 동작이 달라지는 경우가 있어요. 특정 버전을 고정하려면 패키지명 뒤에 @버전번호를 붙이면 됩니다. 예: "@modelcontextprotocol/server-github@1.0.0"
정리
Claude Code에서 MCP 서버를 연결하는 과정을 정리하면 이렇습니다.
- 설정 파일을 정한다 — 프로젝트별이면
.claude/settings.json, 전역이면 홈 디렉토리의~/.claude/settings.json mcpServers키 안에 서버 정보를 추가한다 — command, args, env 세 가지만 알면 대부분 해결됩니다- Claude Code를 재시작하고
/mcp로 연결 상태를 확인한다
처음엔 filesystem 서버 하나부터 시작해보는 걸 권합니다. 설정이 가장 단순하고, “이 폴더 안에서 파일 찾아줘”처럼 바로 체감할 수 있는 기능이라서요. 연결이 된다는 감이 잡히면 github이나 검색 서버로 확장하면 됩니다.
MCP 서버 생태계는 빠르게 넓어지고 있어서, 지금 이 시점에도 새로운 서버들이 계속 공개되고 있습니다. MCP 공식 GitHub에서 카탈로그를 확인해보면 내 업무에 맞는 서버를 찾는 데 도움이 됩니다.