부록 B. MCP 서버 가이드

이 부록에서 배우는 것

MCP가 무엇인지
비개발자도 쓸 수 있는 MCP 서버
설정 방법

MCP란?

Model Context Protocol의 약자입니다.

쉽게 말하면: Claude Code가 외부 도구를 사용할 수 있게 해주는 연결고리

MCP 없이:

Claude Code는 로컬 파일만 접근
외부 서비스 연동 불가

MCP 있으면:

Notion, Slack, GitHub 등 연동
웹 검색, 브라우저 자동화
데이터베이스 접근

비개발자가 알아야 할 것

꼭 알아야 할 개념

개념	설명
MCP 서버	특정 서비스와 연결해주는 프로그램
MCP 클라이언트	Claude Code (MCP 서버를 사용하는 쪽)
`.mcp.json`	MCP 설정 파일

몰라도 되는 것

서버 개발 방법
프로토콜 상세 스펙
내부 동작 원리

유용한 MCP 서버 목록

파일/문서 관련

서버	기능	설치 난이도
filesystem	파일 시스템 접근	쉬움
google-drive	Google Drive 연동	중간
notion	Notion 연동	중간

검색/웹

서버	기능	설치 난이도
brave-search	Brave 검색	쉬움
fetch	웹페이지 가져오기	쉬움
puppeteer	브라우저 자동화	중간

생산성

서버	기능	설치 난이도
slack	Slack 메시지/채널	중간
github	GitHub 이슈/PR	중간
memory	대화 기억 저장	쉬움

설정 방법

1단계: 설정 파일 위치

# 전역 설정 (모든 프로젝트)
~/.claude/mcp.json

# 프로젝트별 설정
./.mcp.json

2단계: 기본 구조

{
  "mcpServers": {
    "서버이름": {
      "command": "실행 명령어",
      "args": ["인자1", "인자2"],
      "env": {
        "API_KEY": "키값"
      }
    }
  }
}

3단계: Claude에게 설정 요청

> MCP 서버 [서버이름]을 설정해줘.
> [필요한 정보 제공]

서버별 설정 예시

Filesystem (파일 시스템)

로컬 파일에 접근하는 기본 서버

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropics/mcp-server-filesystem",
        "/Users/username/Documents",
        "/Users/username/Desktop"
      ]
    }
  }
}

설정 방법

> filesystem MCP 서버 설정해줘.
> 접근할 폴더: /Users/username/Documents

Brave Search (웹 검색)

웹 검색 기능 추가

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

설정 방법

Brave Search API에서 API 키 발급

Claude에게 요청:

> brave-search MCP 서버 설정해줘.
> API 키: [발급받은 키]

Memory (기억 저장)

대화 내용을 저장하고 불러오기

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-memory"]
    }
  }
}

활용

> 이 내용 기억해줘: [내용]
> 지난번에 얘기한 [주제] 뭐였지?

Fetch (웹페이지 가져오기)

웹페이지 내용을 가져와서 분석

{
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-fetch"]
    }
  }
}

활용

> 이 URL 내용 분석해줘: [URL]

실전 설정: 업무용 MCP 세트

기본 세트 (권장)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@anthropics/mcp-server-filesystem",
        "/Users/username/Documents",
        "/Users/username/Projects"
      ]
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-fetch"]
    },
    "memory": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-memory"]
    }
  }
}

마케팅/콘텐츠 세트

{
  "mcpServers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-key"
      }
    },
    "fetch": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-fetch"]
    }
  }
}

PM/기획 세트

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-notion"],
      "env": {
        "NOTION_API_KEY": "your-key"
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-github"],
      "env": {
        "GITHUB_TOKEN": "your-token"
      }
    }
  }
}

문제 해결

”MCP 서버를 찾을 수 없습니다”

원인: 설정 파일 위치가 잘못됨

해결

> 현재 MCP 설정 확인해줘

”API 키가 유효하지 않습니다”

원인: 잘못된 API 키

해결

API 키 재확인
환경변수 재설정

”서버 연결 실패”

원인: 네트워크 또는 서버 문제

해결

# 서버 직접 테스트
npx -y @anthropics/mcp-server-[서버이름]

MCP 사용 팁

1. 필요한 것만 활성화

모든 MCP를 동시에 켜면:

속도 저하
토큰 소모 증가
혼란 가능

권장: 작업에 필요한 서버만 활성화

2. 프로젝트별 설정

전역보다 프로젝트별 설정 권장:

.mcp.json 파일을 프로젝트 루트에
git에 커밋하면 팀 공유 가능 (API 키 제외)

3. API 키 보안

# .gitignore에 추가
.mcp.json  # API 키 포함된 경우

또는 환경변수로 분리:

{
  "env": {
    "API_KEY": "${MY_API_KEY}" // 환경변수 참조
  }
}

자주 쓰는 MCP 명령어

서버 상태 확인

> 현재 연결된 MCP 서버 목록 보여줘

특정 서버 기능 확인

> [서버이름] MCP 서버로 뭘 할 수 있어?

서버 재시작

> MCP 서버 재시작해줘

참고 자료

리소스	설명
MCP 공식 문서	Model Context Protocol 스펙
modelcontextprotocol/servers	공식 MCP 서버 모음
awesome-mcp-servers	커뮤니티 MCP 서버 큐레이션
mcp-get	MCP 서버 패키지 매니저
Claude MCP 가이드	Anthropic 공식 MCP 문서

다음 단계

→ 부록 C. 트러블슈팅

← 부록 A. 스킬 라이브러리 부록 C. 트러블슈팅 →