Claude Code MCP 서버는 GitHub·브라우저·DB를 터미널에서 직접 제어하게 만드는 오픈 표준으로, 이 가이드에서 개념 이해와 첫 연결 실습을 20분 안에 완료합니다.
Claude Code를 설치하고 첫 세션까지 마쳤는데, "분명히 더 많은 게 가능하다고 했는데 아직 터미널 안에서 파일 읽고 수정하는 수준에 머물러 있다"는 느낌이 드셨다면 정확히 다음 단계에 와 있는 것입니다. Claude Code가 진짜 힘을 발휘하는 순간은 외부 도구와 연결될 때이고, 그 연결을 가능하게 해주는 것이 바로 MCP(Model Context Protocol)입니다.
MCP가 매력적인 이유는 크게 세 가지입니다. 첫째, 오픈 표준이라 Claude Code뿐 아니라 Cursor, Windsurf, VS Code 등 어떤 AI 클라이언트에서도 같은 서버를 재사용할 수 있습니다. 둘째, 명령어 한 줄로 연결됩니다. 복잡한 API 코드를 직접 짤 필요가 없습니다. 셋째, Claude Code의 Tool Search 기능이 연결된 서버의 도구를 필요할 때만 불러오기 때문에 10개 이상 서버를 연결해도 컨텍스트 부담이 거의 없습니다.
이 글에서는 MCP가 무엇인지 개념부터 정리하고, Claude Code에서 MCP 서버를 처음 연결하는 실습 2가지(GitHub MCP, Playwright MCP)를 단계별로 따라갑니다. 마지막으로 입문자가 반드시 알아야 할 안전 수칙까지 다루겠습니다. Claude Code 설치 가이드를 아직 안 보셨다면 먼저 설치를 마치고 오시는 것을 추천드립니다.
MCP란? Claude Code에 "팔다리"를 달아주는 오픈 표준
MCP(Model Context Protocol)는 Anthropic이 2024년 11월에 공개한 오픈 표준으로, AI 모델이 외부 도구·데이터 소스·서비스와 통신하는 방식을 하나의 규격으로 통일한 프로토콜입니다. 비유하자면 USB-C 충전 케이블과 비슷합니다. 예전에는 기기마다 전용 충전기가 필요했듯이, AI 도구마다 GitHub, Notion, DB에 접속하려면 각각 전용 코드를 짜야 했습니다. MCP는 "하나의 규격으로 모든 도구에 연결"을 가능하게 해줍니다.
MCP 서버가 노출하는 핵심 요소(primitive)는 세 가지입니다.
- Resources — 원시 데이터 (DB 레코드, 파일 내용 등)
- Tools — 실행 가능한 동작 (GitHub PR 생성, Slack 메시지 전송 등)
- Prompts — 특정 워크플로를 위한 재사용 가능한 템플릿
2025년 초 OpenAI와 Google DeepMind도 MCP를 채택했고, 2025년 12월에는 Linux Foundation의 Agentic AI Foundation에 기증되어 명실상부한 업계 표준이 됐습니다. 즉 Claude Code에서 설정한 MCP 서버를 Cursor나 Windsurf에서도 그대로 재사용할 수 있습니다.
MCP가 없을 때 vs 있을 때, 실전 체감 차이
MCP의 가치를 가장 빠르게 이해하는 방법은 "있을 때와 없을 때"를 비교하는 것입니다.
| 상황 | MCP 없이 | MCP 연결 후 |
|---|---|---|
| GitHub 이슈 확인 | 브라우저 열고 → GitHub 이동 → 이슈 검색 → 복사 → 터미널에 붙여넣기 | "인증 관련 이슈 찾아줘" 한 마디로 끝 |
| 배포된 앱 테스트 | 브라우저 열고 → 수동 클릭 → 스크린샷 → 에러 복사 | "배포 URL 접속해서 로그인 폼 테스트해줘" → 자동 실행 |
| 에러 디버깅 | Sentry 대시보드 열고 → 스택 트레이스 복사 → Claude에게 설명 | "이번 주 상위 에러 알려줘" → 스택 트레이스까지 자동으로 가져옴 |
💡 필자의 체감: MCP를 처음 연결한 날, GitHub MCP 하나만으로도 "브라우저 ↔ 터미널" 컨텍스트 스위칭 횟수가 하루 약 30회에서 5회 이하로 줄었습니다. 컨텍스트 스위칭이 줄어드니 집중 시간도 자연스럽게 늘어났습니다. MCP 없이 Claude Code를 쓰는 건, 진짜로 전체 역량의 절반만 쓰는 것과 같다고 느꼈습니다.
MCP 3가지 핵심 개념 — Host·Server·Scope
1. Host와 Server의 관계
MCP 구조에서 Host는 요청을 시작하는 쪽(Claude Code, Claude Desktop, Cursor 등)이고, Server는 외부 서비스의 기능을 MCP 규격으로 노출하는 프로그램입니다. Host가 Server에 "GitHub에서 이슈 목록 가져와"라고 요청하면, Server가 GitHub API를 호출해 결과를 돌려주는 구조입니다.
2. 3가지 Scope — 어디까지 적용할 것인가
Claude Code에서 MCP 서버를 추가할 때 --scope 옵션으로 적용 범위를 정합니다. 이 개념은 입문 단계에서 꼭 이해해야 하는 부분입니다.
| Scope | 적용 범위 | 설정 저장 위치 | 언제 쓰나 |
|---|---|---|---|
--scope user |
모든 프로젝트에서 전역 사용 | ~/.claude.json |
GitHub, 검색 등 항상 쓰는 서버 |
--scope local (기본값) |
이 프로젝트, 내 PC에서만 | 프로젝트 내 로컬 설정 | 프로젝트 전용 DB, Sentry 등 |
--scope project |
이 프로젝트, 팀원 모두 공유 | .mcp.json (Git에 포함) |
팀 전체가 같은 서버를 쓸 때 |
입문 단계에서는 대부분 --scope local(기본값) 또는 --scope user만 쓰시면 충분합니다. 팀 프로젝트에서 함께 공유해야 하는 서버만 --scope project를 사용하시면 됩니다.
3. Tool Search — 10개 이상 연결해도 괜찮은 이유
Claude Code에는 Tool Search(도구 검색)라는 고유 기능이 있습니다. 다른 AI 클라이언트(Cursor, Claude Desktop 등)는 연결된 MCP 서버의 모든 도구 정의를 한꺼번에 컨텍스트에 로드합니다. 그래서 서버를 많이 연결하면 컨텍스트 창이 도구 설명으로 가득 차 성능이 떨어집니다. 반면 Claude Code는 필요할 때만 해당 도구의 정의를 가져오는 lazy loading 방식을 써서, 컨텍스트 사용량을 약 95% 줄입니다. 따라서 10개 이상의 서버를 연결해도 체감 속도 저하가 거의 없습니다.
4단계 따라하기 — 첫 MCP 서버 연결 (GitHub)
가장 많은 개발자가 첫 번째로 연결하는 MCP 서버는 GitHub MCP입니다. 이슈 검색, PR 리뷰, 커밋 분석, 코드 검색을 터미널에서 자연어로 할 수 있게 됩니다. 아래 4단계를 따라가 보세요.
Step 1. GitHub MCP 서버 추가 명령어 실행
터미널에서 다음 명령어를 실행합니다.
claude mcp add github --scope user--scope user를 사용한 이유는 GitHub은 어떤 프로젝트에서든 쓸 가능성이 높은 서버이기 때문입니다. 전역으로 한 번만 설정하면 모든 세션에서 바로 사용할 수 있습니다.
Step 2. OAuth 인증 완료하기
명령어를 실행하면 브라우저가 열리며 GitHub OAuth 인증 화면이 나타납니다. "Authorize" 버튼을 눌러 Claude Code에 리포지토리 접근 권한을 부여합니다. 인증이 완료되면 터미널에 성공 메시지가 표시됩니다.
Step 3. 연결 확인하기
Claude Code 세션을 시작한 뒤, 아래 명령어로 현재 활성화된 MCP 서버 목록을 확인합니다.
claude mcp list목록에 github가 나오면 연결 성공입니다.
Step 4. 첫 사용 — 자연어로 GitHub 다루기
이제 Claude Code 세션에서 자연어로 GitHub을 다룰 수 있습니다.
이 리포지토리에 열려 있는 이슈 보여줘
최근 PR 변경사항 리뷰해줘
인증 관련 코드를 다른 리포지토리에서 검색해줘처음으로 GitHub 이슈 목록이 터미널에 출력되는 순간, "아, MCP가 이런 거구나"라는 감이 확 올 것입니다.
두 번째 연결 실습 — Playwright 브라우저 자동화
두 번째 MCP 서버로 Playwright MCP를 추천드립니다. Playwright는 브라우저를 프로그래밍으로 제어하는 도구인데, MCP로 연결하면 Claude Code가 웹페이지를 열고, 클릭하고, 폼을 채우고, 스크린샷을 찍는 등의 작업을 자연어 한 줄로 시킬 수 있게 됩니다.
설치 및 연결
OS에 따라 명령어 줄바꿈 문법이 다릅니다. 내 환경에 맞는 명령어를 복사해서 사용하세요.
macOS / Linux / WSL (bash/zsh):
claude mcp add playwright --scope local \
-- npx -y @playwright/mcp --headless
Windows PowerShell:
claude mcp add playwright --scope local `
-- npx -y @playwright/mcp --headless
Windows CMD (한 줄로 입력):
claude mcp add playwright --scope local -- npx -y @playwright/mcp --headless⚠️ 줄바꿈 문자 차이: bash/zsh에서는 백슬래시(\), PowerShell에서는 백틱(`)이 줄바꿈 이스케이프입니다. CMD에서는 줄바꿈 이스케이프 없이 한 줄로 입력하는 것이 가장 확실합니다. 또한npx명령어는 Node.js가 설치되어 있어야 동작합니다. Node.js가 없다면 nodejs.org에서 먼저 설치하세요.
별도의 API 키가 필요 없고, 로컬에서만 동작합니다. 다만 Playwright 전용 Chromium 브라우저가 설치되어 있어야 하므로, 처음이라면 아래 명령어를 먼저 실행합니다. (시스템에 Chrome이 있어도 별도로 필요합니다.)
npx playwright install chromium사용 예시 — 한 번에 하나씩 요청하기
Playwright MCP에 명령할 때는 한 번에 하나의 URL과 하나의 작업을 지정하는 것이 가장 정확한 결과를 얻는 방법입니다. 여러 작업을 한꺼번에 던지면 Claude가 "나머지 URL을 알려달라"고 되묻는 경우가 생깁니다.
예시 1 — 특정 URL의 내용 확인:
https://example.com 에 접속해서 제목 텍스트를 가져와줘실제로 실행하면 Claude가 Playwright를 통해 페이지를 열고, "제목 텍스트: Example Domain (h1 헤딩)" 같은 결과를 바로 보여줍니다.
예시 2 — 페이지의 구조 분석:
https://news.ycombinator.com 에 접속해서 상위 5개 뉴스 제목을 가져와줘Hacker News처럼 실제 운영 중인 사이트를 대상으로 하면, Claude가 페이지 구조를 파악해 제목 리스트를 깔끔하게 추출해줍니다. 본인이 배포한 앱이 있다면 그 URL로 바꿔서 테스트해보세요.
예시 3 — 스크린샷 촬영:
https://example.com 스크린샷 찍어서 보여줘이렇게 요청하면 Claude가 페이지 내용을 텍스트로 설명해주지만, 이미지 파일이 디스크에 자동 저장되지는 않습니다. Playwright MCP는 기본적으로 페이지의 접근성 트리(accessibility tree)를 분석해 텍스트로 결과를 반환하는 방식이기 때문입니다.
스크린샷을 이미지 파일로 저장하려면 두 가지 방법이 있습니다.
방법 A — 프롬프트에서 저장 경로를 명시적으로 지정:
https://example.com 스크린샷을 찍어서 ./screenshots/ 폴더에 저장해줘방법 B — MCP 서버 설정 시 --output-dir을 미리 지정:
이 방법을 쓰면 매번 경로를 말하지 않아도 스크린샷이 자동으로 지정 폴더에 저장됩니다.
macOS / Linux / WSL:
claude mcp add playwright --scope local \
-- npx -y @playwright/mcp --headless --output-dir ./screenshots
Windows PowerShell:
claude mcp add playwright --scope local `
-- npx -y @playwright/mcp --headless --output-dir ./screenshots
Windows CMD (한 줄):
claude mcp add playwright --scope local -- npx -y @playwright/mcp --headless --output-dir ./screenshots💡 저장 위치 정리:--output-dir을 지정하지 않으면 스크린샷은 프로젝트 루트의.playwright-mcp/폴더 또는 OS 임시 디렉토리(os.tmpdir()하위)에 저장됩니다. 저장된 파일을 찾기 어려울 수 있으므로, 처음부터--output-dir을 명시적으로 설정해두는 것을 권장합니다.
Playwright MCP는 GitHub MCP와 성격이 완전히 다릅니다. GitHub MCP가 "코드 관리" 영역이라면, Playwright MCP는 "결과물 검증" 영역입니다. 이 두 가지를 연결하면 "코드 수정 → PR 생성 → 배포 → 브라우저 테스트"까지의 전체 흐름을 터미널 한 곳에서 처리할 수 있게 됩니다.
입문자가 꼭 알아야 할 5가지 안전 수칙
MCP 서버는 강력하지만, 내 자격 증명으로 외부 API를 호출하고 파일을 읽고 쓸 수 있는 프로그램이라는 사실을 항상 염두에 두어야 합니다. 아래 5가지 수칙을 지키면 안전하게 사용할 수 있습니다.
1. 공식 서버를 우선 사용하세요
Anthropic이 직접 관리하거나 해당 서비스 벤더(GitHub, Sentry 등)가 공식 발행한 서버를 선택하는 것이 가장 안전합니다. 커뮤니티 포크는 소스를 직접 확인한 뒤 사용하시는 것을 권장합니다.
2. 최소 권한 원칙을 지키세요
DB 서버를 연결할 때는 읽기 전용(read-only) 계정을 사용하고, API 토큰은 필요한 권한만 부여하세요. 서버에 필요 이상의 접근 권한을 주지 않는 것이 핵심입니다.
3. Scope를 의식적으로 분리하세요
모든 서버를 --scope user(전역)로 설치하면 편하지만, 민감한 서버는 반드시 --scope local로 해당 프로젝트에서만 동작하게 제한하는 것이 안전합니다.
4. 활성 서버를 5~6개 이하로 유지하세요
MCP 서버는 각각 별도 서브프로세스로 실행됩니다. 10개 이상 연결해도 Tool Search 덕분에 컨텍스트 문제는 없지만, 시스템 리소스 측면에서 동시에 활성화된 서버를 5~6개 이하로 유지하는 것이 권장됩니다.
5. 설치 전에 소스를 한 번은 확인하세요
⚠️ MCP 서버는 내 컴퓨터에서 코드를 실행하고 내 자격 증명으로 외부 API를 호출하는 프로그램입니다. 특히 낯선 서버는 설치 전에 GitHub 리포지토리의 소스 코드를 한 번은 훑어보는 습관을 들이시는 것이 안전합니다.
다음 단계 — 추천 MCP 서버 10선 미리보기
GitHub과 Playwright를 성공적으로 연결하셨다면, 다음은 내 워크플로에 맞는 서버를 골라 추가하는 단계입니다. 2026년 기준 개발자들이 가장 많이 사용하는 MCP 서버는 아래와 같습니다.
| 서버 | 역할 | 인증 방식 |
|---|---|---|
| GitHub MCP | 이슈·PR·코드 검색 | OAuth |
| Playwright MCP | 브라우저 자동 테스트 | 로컬 (API 키 없음) |
| PostgreSQL MCP | 자연어 DB 쿼리 | DB 접속 정보 |
| Filesystem MCP | 고급 파일 조작 | 로컬 (API 키 없음) |
| Sentry MCP | 에러 모니터링 연동 | OAuth |
| Notion MCP | 문서·작업 관리 | OAuth |
| Slack MCP | 메시지·채널 연동 | OAuth |
| Figma MCP | 디자인 → 코드 변환 | Dev Mode API 키 |
| Firecrawl MCP | 웹 스크래핑·크롤링 | API 키 (무료 티어 있음) |
| Memory MCP | 지식 그래프 기반 영구 기억 | 로컬 (API 키 없음) |
가장 좋은 출발점은 내가 이미 매일 쓰고 있는 도구를 MCP로 연결하는 것입니다. GitHub을 매일 쓰면 GitHub MCP가, DB를 자주 다루면 PostgreSQL MCP가 최우선입니다. Claude Code 필수 MCP 서버 추천 10선, 설치 명령어까지 한 번에를 함께 참고하시면 더 깊이 있는 설정이 가능합니다.
자주 묻는 질문 (FAQ)
Q. MCP 서버는 Claude Code에서만 쓸 수 있나요?
아닙니다. MCP는 오픈 표준이라 Claude Code, Claude Desktop, Cursor, Windsurf, VS Code(GitHub Copilot 포함), Zed, Replit 등 대부분의 주요 AI 코딩 도구에서 같은 서버를 그대로 사용할 수 있습니다. 설정 파일 위치만 약간 다를 뿐 JSON 구조는 동일합니다.
Q. MCP 서버를 연결하면 추가 비용이 드나요?
MCP 서버 자체는 대부분 오픈소스이고 무료입니다. 다만 서버가 호출하는 외부 API(GitHub API, Firecrawl API 등)에 자체 요금이 있을 수 있습니다. Claude Code의 API 사용량(토큰) 비용은 MCP 연결 여부와 무관하게 Anthropic 요금제를 따릅니다. MCP 서버는 Claude가 도달할 수 있는 범위를 넓혀줄 뿐, 토큰 요금 구조를 바꾸지는 않습니다.
Q. scope를 잘못 설정했는데 나중에 바꿀 수 있나요?
네, 가능합니다. claude mcp remove 명령어로 기존 서버를 제거한 뒤 원하는 scope로 다시 추가하면 됩니다. 또는 ~/.claude.json 파일을 직접 편집해도 됩니다. 변경 후 claude mcp list 로 현재 활성 서버를 확인하시는 것을 권장합니다.
Q. MCP 서버가 내 코드를 외부로 보내나요?
MCP 서버는 로컬에서 실행되는 프로그램입니다. 서버가 연결하는 외부 서비스(GitHub, Notion 등)로 데이터가 전송될 수 있지만, 이는 해당 서비스를 직접 쓸 때와 동일한 수준입니다. 순수 로컬 서버(Filesystem, Playwright 등)는 외부에 데이터를 보내지 않습니다. API 키나 OAuth 토큰의 권한 범위를 최소한으로 설정하는 것이 가장 좋은 보안 관행입니다.
Q. Tool Search가 정확히 뭔가요? 꺼야 하는 경우도 있나요?
Tool Search는 Claude Code가 연결된 MCP 서버의 모든 도구 정의를 한꺼번에 컨텍스트에 올리지 않고, 필요할 때만 해당 도구의 스키마를 가져오는 lazy loading 기능입니다. 이를 통해 컨텍스트 사용량을 약 95% 절약합니다. 기본적으로 활성화되어 있으며, 특별히 끌 이유가 없습니다.
Q. Playwright MCP 설치 시 Chromium이 이미 있는데 다시 설치해야 하나요?
Playwright는 자체 관리 버전의 Chromium을 사용합니다. 시스템에 Chrome이 설치되어 있어도 npx playwright install chromium 으로 Playwright 전용 브라우저를 별도로 설치해야 정상 동작합니다. 이미 다른 프로젝트에서 Playwright를 사용 중이라면 추가 설치 없이 바로 연결 가능합니다.
Q. Windows에서도 모든 MCP 서버가 동작하나요?
대부분의 MCP 서버는 Node.js 기반이므로 Windows에서도 동작합니다. 다만 일부 서버(특히 Linux 전용 도구에 의존하는 서버)는 WSL2 환경에서 사용하시는 것이 안정적입니다. GitHub MCP, Playwright MCP, Notion MCP 등 주요 서버는 Windows 네이티브에서도 정상 동작합니다.
Q. MCP 서버를 직접 만들 수도 있나요?
네, 가능합니다. MCP는 오픈 표준이므로 누구나 서버를 만들 수 있습니다. Python이라면 FastMCP 라이브러리를, Node.js라면 @modelcontextprotocol/sdk 패키지를 사용하면 비교적 간단하게 커스텀 서버를 작성할 수 있습니다. 사내 전용 API나 독자적인 워크플로가 있다면 커스텀 서버를 만들어 Claude Code에 연결하는 것도 좋은 방법입니다.
마무리 — MCP는 Claude Code의 진짜 시작점
MCP를 연결하기 전과 후의 Claude Code는 사실상 다른 도구라고 해도 과언이 아닙니다. 오늘 이 글에서 핵심 3가지를 기억하시면 됩니다. ① MCP는 AI와 외부 도구를 연결하는 오픈 표준이다, ② claude mcp add 명령어 한 줄로 연결된다, ③ 내가 이미 매일 쓰는 도구부터 MCP로 연결하는 것이 가장 효과적이다. GitHub MCP 하나만 연결해도 체감 생산성이 눈에 띄게 달라집니다. 오늘 당장 시도해 보세요.
💬 첫 MCP 서버로 어떤 걸 연결하셨나요? 댓글로 경험을 공유해 주시면 다른 입문자에게 큰 도움이 됩니다.
🔖 설치 명령어를 자주 참고하실 분은 이 글을 북마크해 두시면 편리합니다.
📤 주변에 Claude Code를 쓰면서 MCP는 아직 모르는 분이 있다면 이 글을 공유해 주세요.
📚 다음에 읽으면 좋은 글
ℹ️ 이 블로그는 Google 애드센스를 통해 광고 수익을 얻을 수 있습니다. 자세한 내용은 개인정보처리방침을 참고하세요.
※ 이 글은 2026-04-17 기준으로 작성되었습니다. 최신 정보는 공식 사이트에서 확인하세요.
'개발 도구 & OS' 카테고리의 다른 글
| Claude Code 필수 MCP 서버 추천 10선, 설치 명령어까지 한 번에 (0) | 2026.04.18 |
|---|---|
| Claude Code 설치 가이드, 터미널 첫 세션까지 30분 완성 (0) | 2026.04.16 |
| 바이브 코딩 입문, 비개발자가 첫 앱 만드는 5단계 가이드 (1) | 2026.04.15 |
| API 키 없이 날씨 데이터 가져오는 Open-Meteo 완벽 가이드 2026 (1) | 2026.04.10 |
| 터미널 커스터마이징 완벽 가이드 2026 — fastfetch·starship·tmux 설정 (0) | 2026.04.09 |
