# Claude CLI 완전 가이드 v6: MCP 서버 설정 및 활용

## MCP(Model Context Protocol)란?

MCP는 AI 도구 통합을 위한 오픈소스 표준입니다. Claude Code를 외부 도구, 데이터베이스, API와 연결하여 기능을 확장합니다.

### MCP로 할 수 있는 것

- 이슈 트래커에서 이슈 가져와 구현
- 모니터링 데이터 분석
- 데이터베이스 직접 쿼리
- 외부 서비스 워크플로우 자동화
- 비공개 저장소 접근

---

## 세 가지 연결 방식

### 1. Remote HTTP 서버 (권장)

클라우드 기반 서비스에 HTTPS로 연결:

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

**특징:**
- OAuth 2.0 인증 지원
- 보안 연결
- 권장 방식

### 2. Remote SSE 서버 (구버전)

Server-Sent Events 방식 (HTTP로 대체 예정):

```bash
claude mcp add --transport sse server-name https://sse-endpoint
```

### 3. Local Stdio 서버

로컬 머신에서 프로세스 실행:

```bash
claude mcp add --transport stdio airtable -- npx -y airtable-mcp-server
```

**특징:**
- 로컬 파일/DB 접근에 적합
- 시스템 리소스 직접 사용
- 네트워크 불필요

---

## MCP 서버 관리 명령어

### 서버 추가

```bash
# HTTP 서버 추가
claude mcp add --transport http [이름] [URL]

# Stdio 서버 추가
claude mcp add --transport stdio [이름] -- [명령어]
```

### 서버 목록 확인

```bash
claude mcp list
```

### 특정 서버 정보

```bash
claude mcp get [이름]
```

### 서버 제거

```bash
claude mcp remove [이름]
```

### 세션 내 상태 확인

```
/mcp
```

---

## 설정 범위 (Scope)

### Local 설정 (기본값)

현재 프로젝트에서만 사용, 개인용:

```bash
claude mcp add --local github -- npx -y @mcpHub/github-mcp
```

설정 저장: `.mcp.json` (git-ignored)

### Project 설정

팀과 공유, 버전 관리:

```bash
claude mcp add --project github -- npx -y @mcpHub/github-mcp
```

설정 저장: `.mcp.json` (git에 포함)

### User 설정

모든 프로젝트에서 사용:

```bash
claude mcp add github -- npx -y @mcpHub/github-mcp
```

설정 저장: `~/.claude/mcp.json`

---

## 인증 처리

### OAuth 2.0 인증

많은 클라우드 서비스는 OAuth 인증이 필요합니다:

```
/mcp
```

이 명령으로 MCP 서버 목록과 인증 상태를 확인하고, 필요한 서버에 대해 인증을 진행합니다.

**인증 흐름:**
1. `/mcp` 실행
2. 인증 필요한 서버 선택
3. 브라우저에서 OAuth 로그인
4. 토큰 자동 저장 및 갱신

---

## MCP 리소스 참조

외부 데이터를 `@` 문법으로 참조:

```
@github:issue://123
@notion:database://abc123
@database:table://users
```

Claude가 해당 리소스에 직접 접근하여 분석합니다.

---

## MCP 슬래시 명령어

MCP 서버가 제공하는 프롬프트는 슬래시 명령어로 사용:

```
/mcp__[서버이름]__[프롬프트이름] [인수]
```

**예시:**

```
/mcp__github__list_prs
/mcp__github__get_issue 123
/mcp__notion__search_pages
```

---

## 주요 MCP 서버 설정 예제

### GitHub MCP

```bash
claude mcp add --transport stdio github -- npx -y @modelcontextprotocol/server-github
```

**기능:**
- 저장소 탐색
- PR/이슈 관리
- 파일 읽기/쓰기
- Actions 상태 확인

**사용 예시:**

```
> 최근 PR 목록을 보여줘
> 이슈 #42의 내용을 구현해줘
```

### Notion MCP

```bash
claude mcp add --transport http notion https://mcp.notion.com/mcp
```

**기능:**
- 페이지 검색
- 데이터베이스 쿼리
- 컨텐츠 생성/편집

**사용 예시:**

```
> 프로젝트 문서 데이터베이스에서 최신 스펙을 가져와줘
```

### PostgreSQL MCP

```bash
claude mcp add --transport stdio postgres -- npx -y @modelcontextprotocol/server-postgres
```

**환경 변수 설정:**

```bash
export DATABASE_URL="postgresql://user:pass@localhost:5432/dbname"
```

**기능:**
- 스키마 조회
- 쿼리 실행
- 데이터 분석

**사용 예시:**

```
> users 테이블의 스키마를 보여줘
> 최근 7일간 가입자 수를 분석해줘
```

### Filesystem MCP

```bash
claude mcp add --transport stdio fs -- npx -y @modelcontextprotocol/server-filesystem /allowed/path
```

**기능:**
- 지정 경로 파일 접근
- 디렉토리 탐색
- 파일 읽기/쓰기

### Slack MCP

```bash
claude mcp add --transport stdio slack -- npx -y @modelcontextprotocol/server-slack
```

**기능:**
- 채널 메시지 읽기
- 메시지 전송
- 검색

### Context7 (문서 조회)

```bash
claude mcp add --transport stdio context7 -- npx -y @context7/mcp-server
```

**기능:**
- 라이브러리 최신 문서 조회
- 코드 예제 검색
- API 레퍼런스 확인

**사용 예시:**

```
> React 18의 useTransition 훅 사용법을 알려줘
```

---

## 설정 파일 구조

### .mcp.json 예시

```json
{
  "mcpServers": {
    "github": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "notion": {
      "type": "http",
      "url": "https://mcp.notion.com/mcp"
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}
```

### 환경 변수 활용

민감한 정보는 환경 변수로:

```json
{
  "mcpServers": {
    "custom-api": {
      "type": "http",
      "url": "https://api.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${API_TOKEN}"
      }
    }
  }
}
```

---

## MCP 활용 워크플로우

### 이슈 기반 개발

```
> @github:issue://42 이 이슈를 구현해줘
```

Claude가:
1. GitHub에서 이슈 내용 가져옴
2. 요구사항 분석
3. 코드 구현
4. 테스트 작성

### 데이터 분석

```
> 데이터베이스에서 이번 달 매출 데이터를 분석하고
> Notion에 보고서로 정리해줘
```

Claude가:
1. PostgreSQL에서 데이터 쿼리
2. 분석 수행
3. Notion 페이지 생성

### 문서화 자동화

```
> 이 API의 변경사항을 GitHub PR에서 확인하고
> Notion 문서를 업데이트해줘
```

---

## 엔터프라이즈 설정

관리자가 승인된 MCP 서버를 중앙에서 관리:

`managed-mcp.json`:

```json
{
  "approvedServers": [
    "github",
    "notion",
    "internal-api"
  ],
  "blockedServers": [
    "untrusted-server"
  ]
}
```

---

## 문제 해결

### 서버 연결 실패

```bash
# 상태 확인
claude mcp list
/mcp

# 서버 재시작
claude mcp remove [name]
claude mcp add [name] ...
```

### 인증 만료

```
/mcp
```

인증이 만료된 서버를 다시 인증합니다.

### 로그 확인

```bash
claude --verbose
```

상세 로그에서 MCP 연결 문제를 확인합니다.

---

## 보안 고려사항

1. **최소 권한**: 필요한 권한만 부여
2. **토큰 관리**: 환경 변수로 관리, 코드에 하드코딩 금지
3. **프로젝트 범위**: 민감한 서버는 `--local`로 설정
4. **정기 검토**: 사용하지 않는 MCP 서버 제거

---

## 다음 단계

v6에서는 MCP 서버 설정과 활용을 다뤘습니다.

**다음 v7에서는**:
- Hooks의 개념
- Hook 이벤트 유형
- 자동화 설정 방법
- 실용 예제

를 상세히 알아봅니다.

---

## 빠른 참조

```
MCP 명령어:
  claude mcp add      서버 추가
  claude mcp list     서버 목록
  claude mcp get      서버 정보
  claude mcp remove   서버 제거
  /mcp               세션 내 관리

범위 옵션:
  --local    현재 프로젝트만 (기본값)
  --project  팀 공유 (git)
  (없음)     사용자 전역

전송 방식:
  --transport http    HTTPS 연결
  --transport stdio   로컬 프로세스
  --transport sse     SSE (구버전)

주요 서버:
  github     저장소/PR/이슈 관리
  notion     문서/데이터베이스
  postgres   SQL 데이터베이스
  slack      팀 커뮤니케이션
  context7   라이브러리 문서
```

---

*Claude CLI 완전 가이드 시리즈 v6/10*