첫 번째 MCP 연결: Claude Desktop 설정

레슨 1에서 MCP가 “AI의 USB-C"라는 걸 배웠습니다. 이제 그 USB-C 케이블을 실제로 꽂아볼 차례입니다.

준비물

시작하기 전에 필요한 것들:

1. Claude Desktop — claude.ai/download에서 다운로드 (무료)
2. Node.js (v18 이상) — 대부분의 MCP 서버가 npm으로 설치됨
3. 텍스트 에디터 — VS Code, Cursor, 또는 아무거나
4. 터미널 — macOS Terminal, Windows PowerShell, 또는 선호하는 터미널

✅ Quick Check: MCP 서버를 실행하려면 왜 Node.js가 필요할까요? (대부분의 공개 MCP 서버가 npm 패키지로 배포되기 때문입니다. Python 기반 서버는 uvx를 사용합니다.)

핵심 파일: claude_desktop_config.json

Claude Desktop의 MCP 설정은 하나의 JSON 파일로 관리됩니다.

파일 위치:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

파일이 없으면 직접 만들면 됩니다. 기본 구조는 이렇습니다:

{
  "mcpServers": {
    "서버이름": {
      "command": "실행할 명령어",
      "args": ["인자1", "인자2"],
      "env": {
        "API_KEY": "여기에_키_입력"
      }
    }
  }
}

세 가지 필드:

• command — MCP 서버를 실행할 명령어 (npx, uvx, node 등)
• args — 명령어에 전달할 인자들
• env — 환경 변수 (API 키, 토큰 등 민감 정보)

첫 번째 MCP 서버 연결: 파일시스템

가장 간단한 MCP 서버인 파일시스템 서버로 시작합니다. 이 서버는 Claude가 지정한 폴더의 파일을 읽고, 검색하고, 수정할 수 있게 해줍니다.

Step 1: 설정 파일 열기

macOS 터미널에서:

# 설정 파일이 있는 폴더 열기
open ~/Library/Application\ Support/Claude/

# 파일이 없으면 생성
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json

Step 2: 서버 설정 추가

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/내이름/Documents"
      ]
    }
  }
}

/Users/내이름/Documents를 실제 경로로 바꾸세요. 이 경로가 Claude가 접근할 수 있는 범위입니다 — 지정하지 않은 폴더에는 접근 불가.

Step 3: Claude Desktop 재시작

설정을 저장한 뒤 Claude Desktop을 완전히 종료하고 다시 실행합니다. (macOS: Cmd+Q 후 재실행)

Step 4: 연결 확인

채팅 입력창 옆에 망치(🔨) 아이콘이 보이고, 옆에 숫자가 표시되면 성공입니다. 아이콘을 클릭하면 연결된 도구 목록이 나옵니다.

테스트 질문: “내 Documents 폴더에 어떤 파일들이 있어?”

Claude가 실제 파일 목록을 보여주면 — MCP가 작동하는 겁니다.

✅ Quick Check: 파일시스템 서버에서 특정 폴더만 지정하는 이유는? (보안입니다. MCP는 최소 권한 원칙을 따릅니다 — Claude가 전체 하드디스크에 접근하면 위험하니까, 필요한 폴더만 노출합니다.)

서버 여러 개 동시에 연결하기

MCP의 진짜 힘은 여러 서버를 동시에 연결할 때 나옵니다. mcpServers 아래에 서버를 추가하면 됩니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/내이름/Documents"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "여기에_API키"
      }
    }
  }
}

이렇게 하면 Claude가 로컬 파일도 읽고, 웹 검색도 할 수 있습니다. “내 프로젝트 README를 읽고, 비슷한 오픈소스 프로젝트를 검색해줘” 같은 복합 작업이 가능해집니다.

env 블록: API 키 안전하게 관리하기

절대 하면 안 되는 것:

{
  "command": "npx",
  "args": ["-y", "some-server", "--api-key", "sk-abc123실제키"]
}

args에 API 키를 직접 넣으면 설정 파일에 평문으로 저장됩니다. 실수로 공유하거나 GitHub에 올리면 큰일.

올바른 방법:

{
  "command": "npx",
  "args": ["-y", "some-server"],
  "env": {
    "API_KEY": "sk-abc123실제키"
  }
}

env 블록을 사용하면 환경 변수로 전달됩니다. 더 안전한 방법은 .env 파일이나 시스템 환경 변수를 활용하는 건데, 이건 레슨 7(보안)에서 자세히 다룹니다.

연결이 안 될 때: 트러블슈팅

가장 흔한 실수: JSON에서 마지막 항목 뒤에 쉼표를 붙이는 것. JavaScript는 허용하지만 JSON은 안 됩니다.

// ❌ 틀림
{ "servers": { "a": {}, "b": {}, } }

// ✅ 맞음
{ "servers": { "a": {}, "b": {} } }

핵심 정리

• Claude Desktop MCP 설정은 claude_desktop_config.json 하나로 관리
• 파일시스템 서버가 가장 기본적인 MCP 서버 — 로컬 파일 읽기/검색/수정
• env 블록으로 API 키를 안전하게 전달 — args에 직접 쓰지 말 것
• 서버 여러 개를 동시에 연결해서 복합 작업 수행 가능
• 연결 성공 여부는 망치 아이콘 + 도구 수로 확인

다음 레슨

Claude Desktop에 MCP 서버를 연결하는 법을 알았으니, 이제 질문은 — “어떤 서버를 쓸까?” 입니다. 레슨 3에서 개발자가 바로 써먹을 수 있는 필수 MCP 서버 10개를 소개합니다.