MCP 서버 설정 완벽 가이드: Claude Code의 능력을 확장하는 방법

Claude Code가 파일만 읽고 쓰는 것으로는 부족하다고 느끼셨나요? 데이터베이스를 직접 조회하거나, Slack에 메시지를 보내거나, 외부 API를 호출하고 싶었던 적이 있으신가요?

MCP 서버를 설정하면 이 모든 것이 가능해집니다. 이 글에서는 MCP가 무엇인지부터 실제로 서버를 설정하고 Claude Code와 연동하는 방법까지, 초보자도 따라할 수 있도록 단계별로 안내합니다.

MCP란 무엇인가?

MCP(Model Context Protocol)는 Anthropic에서 개발한 오픈 프로토콜로, AI 모델이 외부 도구와 데이터 소스에 안전하게 접근할 수 있도록 해주는 표준입니다.

MCP의 구조

MCP는 세 가지 핵심 구성요소로 이루어집니다:

┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│   Claude    │────▶│ MCP Client  │────▶│ MCP Server  │
│   (AI)      │     │ (Claude     │     │ (Tool/Data) │
│             │◀────│  Code)      │◀────│             │
└─────────────┘     └─────────────┘     └─────────────┘

MCP Client: Claude Code가 내장한 클라이언트로, MCP 서버와 통신합니다
MCP Server: 특정 기능을 제공하는 서버 (DB 조회, 파일 접근, API 호출 등)
Protocol: 클라이언트와 서버 간의 통신 규약

MCP가 제공하는 것

MCP 서버는 세 가지 유형의 기능을 Claude에게 제공할 수 있습니다:

유형	설명	예시
Tools	Claude가 호출할 수 있는 함수	DB 쿼리, API 호출
Resources	데이터 접근 경로	파일, 문서, 설정
Prompts	미리 정의된 프롬프트 템플릿	코드 리뷰, 문서화

MCP 서버가 필요한 이유

기본 Claude Code도 충분히 강력하지만, MCP 서버를 연결하면 가능성이 크게 확장됩니다.

기본 Claude Code vs MCP 연동 Claude Code

기능	기본	MCP 연동
파일 읽기/쓰기	✅	✅
터미널 명령	✅	✅
데이터베이스 조회	❌	✅
외부 API 호출	❌	✅
브라우저 자동화	❌	✅
Slack/Discord 연동	❌	✅
웹 스크래핑	제한적	✅

실제 사용 사례

1. 데이터베이스 연동

"users 테이블에서 최근 가입한 10명 조회해줘"
→ Claude가 직접 SQL 쿼리 실행

2. Slack 연동

"배포 완료 메시지를 #deployments 채널에 보내줘"
→ Claude가 Slack API 호출

3. 웹 검색

"이 에러 메시지로 검색해서 해결책 찾아줘"
→ Claude가 실시간 웹 검색

설치 전 준비사항

MCP 서버를 설정하기 전에 다음 환경이 준비되어 있어야 합니다.

필수 요구사항

항목	요구 버전	확인 방법
Claude Code	최신 버전	`claude --version`
Node.js	18.0+	`node --version`
npm/npx	8.0+	`npm --version`

Claude Code 설치 확인

아직 Claude Code가 설치되어 있지 않다면 먼저 설치하세요:

npm install -g @anthropic-ai/claude-code

설정 파일 위치 확인

MCP 설정은 다음 위치에 저장됩니다:

macOS/Linux: ~/.claude/settings.json
Windows: %APPDATA%\claude\settings.json
프로젝트별: .claude/settings.json (프로젝트 루트)

MCP 서버 설정 방법

이제 실제로 MCP 서버를 설정해 보겠습니다. 가장 간단한 공식 MCP 서버부터 시작합니다.

방법 1: Claude Code 내장 명령어 (권장)

Claude Code에서 직접 MCP 서버를 추가할 수 있습니다:

claude mcp add

대화형으로 서버를 선택하고 설정할 수 있습니다.

방법 2: 설정 파일 직접 수정

~/.claude/settings.json 파일을 열고 mcpServers 섹션을 추가합니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
    }
  }
}

방법 3: 프로젝트별 설정

프로젝트 루트에 .claude/settings.json을 생성하면 해당 프로젝트에서만 MCP 서버가 활성화됩니다:

{
  "mcpServers": {
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "./database.db"]
    }
  }
}

설정 확인

설정이 완료되면 Claude Code를 재시작하고 확인합니다:

claude
> /mcp

연결된 MCP 서버 목록이 표시되면 성공입니다.

실전 예제: 파일 시스템 MCP

가장 많이 사용되는 MCP 서버인 파일 시스템 MCP를 설정해 보겠습니다.

왜 파일 시스템 MCP가 필요한가?

기본 Claude Code도 파일을 읽고 쓸 수 있지만, 파일 시스템 MCP는 다음 기능을 추가합니다:

디렉토리 트리 조회: 폴더 구조를 한눈에 파악
대용량 파일 처리: 큰 파일도 효율적으로 처리
파일 검색: 패턴으로 파일 찾기
접근 범위 제한: 보안을 위한 디렉토리 제한

설치 및 설정

1단계: 설정 파일 수정

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/projects"
      ]
    }
  }
}

2단계: Claude Code 재시작

claude

3단계: 테스트

> /mcp
filesystem: connected

> projects 폴더의 구조를 보여줘

사용 예시

파일 시스템 MCP가 연결되면 다음과 같은 작업이 가능합니다:

> ~/Documents 폴더에서 .md 파일 모두 찾아줘
> 이 프로젝트의 전체 구조를 트리로 보여줘
> src 폴더의 모든 TypeScript 파일 목록 가져와

고급 설정: 커스텀 MCP 서버

공식 MCP 서버 외에도 커뮤니티 서버를 사용하거나 직접 만들 수 있습니다.

서버	기능	설치 명령
SQLite	데이터베이스 조회	`@modelcontextprotocol/server-sqlite`
PostgreSQL	PostgreSQL 연동	`@modelcontextprotocol/server-postgres`
Brave Search	웹 검색	`@anthropics/mcp-server-brave-search`
Puppeteer	브라우저 자동화	`@anthropics/mcp-server-puppeteer`
Slack	Slack 연동	`@anthropics/mcp-server-slack`

여러 MCP 서버 동시 사용

여러 서버를 동시에 설정할 수 있습니다:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/projects"]
    },
    "sqlite": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-sqlite", "./app.db"]
    },
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@anthropics/mcp-server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your-api-key"
      }
    }
  }
}

커스텀 MCP 서버 만들기

자신만의 MCP 서버를 만들 수도 있습니다. TypeScript SDK를 사용한 기본 템플릿:

import { Server } from "@modelcontextprotocol/sdk/server";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";

const server = new Server({
  name: "my-custom-server",
  version: "1.0.0"
});

// Tool 정의
server.tool("hello", "인사말을 반환합니다", {
  name: { type: "string", description: "이름" }
}, async (args) => {
  return { greeting: `안녕하세요, ${args.name}님!` };
});

// 서버 시작
const transport = new StdioServerTransport();
server.connect(transport);

트러블슈팅

MCP 서버 설정 중 자주 발생하는 문제와 해결 방법입니다.

문제 1: MCP 서버가 연결되지 않음

증상: /mcp 명령어에 서버가 표시되지 않음

해결책:
1. 설정 파일 경로 확인: ~/.claude/settings.json
2. JSON 문법 오류 확인 (쉼표, 따옴표)
3. Claude Code 재시작

# JSON 문법 검증
cat ~/.claude/settings.json | python3 -m json.tool

문제 2: “Command not found” 오류

증상: MCP 서버 실행 시 명령어를 찾을 수 없음

해결책:
1. Node.js 설치 확인
2. npx가 PATH에 있는지 확인
3. 절대 경로로 command 지정

{
  "command": "/usr/local/bin/npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"]
}

문제 3: 권한 오류

증상: “Permission denied” 또는 접근 거부

해결책:
1. 디렉토리 권한 확인
2. MCP 서버에 올바른 경로 전달
3. 환경 변수 확인 (API 키 등)

문제 4: 서버가 자주 끊김

증상: MCP 서버 연결이 불안정

해결책:

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path"],
      "timeout": 60000
    }
  }
}

자주 묻는 질문

Q: MCP 서버는 무료인가요?

대부분의 MCP 서버는 무료입니다. Anthropic 공식 서버와 커뮤니티 서버 모두 오픈소스로 제공됩니다. 다만, 일부 서버(Brave Search 등)는 해당 서비스의 API 키가 필요할 수 있습니다.

Q: MCP 서버를 사용하면 보안에 문제가 없나요?

MCP는 권한 기반 접근 제어를 제공합니다:
– 파일 시스템: 특정 디렉토리만 접근 허용
– 데이터베이스: 읽기 전용 모드 지원
– 모든 작업: Claude Code가 실행 전 확인 요청

민감한 데이터가 있다면 별도의 MCP 서버 인스턴스를 만들어 격리하는 것을 권장합니다.

Q: 한 번에 여러 MCP 서버를 연결할 수 있나요?

네, 무제한으로 연결할 수 있습니다. 단, 서버가 많아지면 Claude Code 시작 시간이 길어질 수 있으니 필요한 서버만 활성화하세요.

Q: 프로젝트마다 다른 MCP 설정을 사용할 수 있나요?

네, 프로젝트 루트에 .claude/settings.json 파일을 만들면 해당 프로젝트에서만 적용됩니다. 전역 설정(~/.claude/settings.json)보다 프로젝트 설정이 우선합니다.

Q: MCP 서버를 직접 만들려면 어떻게 해야 하나요?

Anthropic에서 제공하는 MCP SDK를 사용하면 됩니다:
– TypeScript SDK: @modelcontextprotocol/sdk
– Python SDK: mcp

공식 문서: https://modelcontextprotocol.io

마치며

이 글에서 MCP 서버의 개념부터 실제 설정 방법까지 살펴보았습니다. 핵심을 정리하면:

MCP는 Claude Code의 기능을 확장하는 프로토콜입니다
설정은 간단합니다 – JSON 파일 하나로 끝
다양한 서버를 연결해 DB, API, 브라우저까지 제어 가능
보안은 권한 기반으로 관리됩니다

MCP 서버를 설정하면 Claude Code가 단순한 코딩 어시스턴트에서 풀스택 자동화 도구로 진화합니다.

지금 바로 ~/.claude/settings.json을 열고 첫 번째 MCP 서버를 추가해 보세요. 파일 시스템 MCP부터 시작하면 금방 익숙해질 것입니다.

MCP 서버 설정에 성공하셨다면, 댓글로 어떤 서버를 사용하고 계신지 공유해 주세요!

MCP 서버 설정 완벽 가이드: Claude Code의 능력을 확장하는 방법

MCP 서버 설정 완벽 가이드: Claude Code의 능력을 확장하는 방법

목차

MCP란 무엇인가?

MCP의 구조

MCP가 제공하는 것

MCP 서버가 필요한 이유

기본 Claude Code vs MCP 연동 Claude Code

실제 사용 사례

설치 전 준비사항

필수 요구사항

Claude Code 설치 확인

설정 파일 위치 확인

MCP 서버 설정 방법

방법 1: Claude Code 내장 명령어 (권장)

방법 2: 설정 파일 직접 수정

방법 3: 프로젝트별 설정

설정 확인

실전 예제: 파일 시스템 MCP

왜 파일 시스템 MCP가 필요한가?

설치 및 설정

사용 예시

고급 설정: 커스텀 MCP 서버

인기 있는 커뮤니티 MCP 서버

여러 MCP 서버 동시 사용

커스텀 MCP 서버 만들기

트러블슈팅

문제 1: MCP 서버가 연결되지 않음

문제 2: “Command not found” 오류

문제 3: 권한 오류

문제 4: 서버가 자주 끊김

자주 묻는 질문

Q: MCP 서버는 무료인가요?

Q: MCP 서버를 사용하면 보안에 문제가 없나요?

Q: 한 번에 여러 MCP 서버를 연결할 수 있나요?

Q: 프로젝트마다 다른 MCP 설정을 사용할 수 있나요?

Q: MCP 서버를 직접 만들려면 어떻게 해야 하나요?

마치며