Claude Code MCP Server 설정 및 실전 활용 가이드

MCP란?

MCP(Model Context Protocol)는 AI 어시스턴트를 외부 도구 및 데이터 소스와 연결하기 위한 오픈 프로토콜입니다. Claude Code는 MCP 클라이언트 역할을 하며, MCP Server를 통해 데이터베이스, API, 다양한 서비스와 상호작용할 수 있습니다.

MCP Server 설정

MCP Server 설정은 .claude/settings.json 또는 ~/.claude/settings.json에 작성합니다:

{
  "mcpServers": {
    "server-name": {
      "command": "executable-command",
      "args": ["arg1", "arg2"],
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

CLI를 통해서도 서버를 추가할 수 있습니다:

claude mcp add server-name -- command arg1 arg2

예제 1: 데이터베이스 연동

PostgreSQL에 직접 쿼리를 실행하는 MCP Server를 설정합니다:

claude mcp add postgres-server -- npx -y @modelcontextprotocol/server-postgres postgresql://user:pass@localhost:5432/mydb

설정이 완료되면 Claude Code 세션에서 데이터베이스를 조회할 수 있습니다:

> users 테이블에서 지난 1주일간 신규 가입자 수를 알려 줘
> 일별 추이를 표 형태로 보여 줘

Claude Code가 자동으로 SQL 쿼리를 생성하고 실행한 뒤 결과를 정리해 줍니다.

예제 2: GitHub 연동

GitHub MCP Server를 사용하면 Claude Code에서 직접 이슈와 PR을 관리할 수 있습니다:

claude mcp add github -- npx -y @modelcontextprotocol/server-github

환경 변수로 토큰을 설정합니다:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

다음과 같은 작업이 가능합니다:

> 저장소의 열린 이슈를 모두 나열해 줘
> Issue #42를 확인하고 수정 브랜치를 만들어서 해결해 줘
> 수정이 완료되면 PR을 만들어 줘

예제 3: 파일시스템 확장

특정 디렉토리에 대한 안전한 접근을 제공하는 MCP Server입니다:

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/directory

예제 4: 웹 스크래핑

Puppeteer MCP Server로 웹 페이지를 가져오고 상호작용할 수 있습니다:

claude mcp add puppeteer -- npx -y @modelcontextprotocol/server-puppeteer

> https://example.com/api/docs 의 API 문서를 읽고
> 해당 API의 클라이언트 라이브러리를 만들어 줘

예제 5: Slack 연동

Slack MCP Server로 채널 메시지를 읽고 알림을 보낼 수 있습니다:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-xxxxxxxxxxxx"
      }
    }
  }
}

> #dev 채널의 최근 메시지를 확인해 줘
> #daily-report 채널에 오늘의 진행 상황을 공유해 줘

MCP Server 관리

등록된 서버 목록 확인

claude mcp list

서버 삭제

claude mcp remove server-name

스코프 설정

MCP Server의 설정 범위를 지정할 수 있습니다:

# 프로젝트 단위 (기본값)
claude mcp add --scope project db-server -- command

# 사용자 전역
claude mcp add --scope user db-server -- command

커스텀 MCP Server 만들기

프로젝트 전용 도구를 커스텀 MCP Server로 만들 수도 있습니다:

// my-mcp-server.ts
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

const server = new McpServer({
  name: "my-project-tools",
  version: "1.0.0",
});

// 커스텀 도구 정의
server.tool(
  "deploy-staging",
  "스테이징 환경에 배포",
  { branch: z.string().describe("배포할 브랜치 이름") },
  async ({ branch }) => {
    // 배포 로직
    return {
      content: [{ type: "text", text: `${branch}를 스테이징에 배포했습니다` }],
    };
  }
);

const transport = new StdioServerTransport();
await server.connect(transport);

다음과 같이 등록합니다:

claude mcp add my-tools -- npx tsx my-mcp-server.ts

보안 고려사항

1. 자격 증명 관리

MCP Server 설정의 토큰과 비밀번호는 환경 변수나 .env 파일로 관리하세요. 절대 Git에 커밋하지 마세요.

2. 접근 범위 제한

최소 권한 원칙을 따르세요. 예를 들어 데이터베이스 MCP Server에는 읽기 전용 사용자를 사용합니다.

3. 로컬 설정 사용

자격 증명이 포함된 설정은 .claude/settings.local.json에 저장하고 .gitignore에 추가하세요.

결론

MCP Server를 활용하면 Claude Code의 역량을 프로젝트 전체 생태계로 확장할 수 있습니다. 데이터베이스 쿼리부터 GitHub 워크플로, Slack 알림까지 Claude Code를 개발 워크플로의 중심 허브로 활용할 수 있습니다. 공식 MCP Server부터 시작하고, 필요에 따라 커스텀 서버를 구축해 보세요.