MCP 서버

Model Context Protocol (MCP) 서버를 통해 Claude Code의 기능을 확장할 수 있습니다.

MCP란?

MCP는 Claude Code가 외부 도구 및 서비스와 통신할 수 있게 해주는 프로토콜입니다. MCP 서버를 통해:

외부 API 통합
데이터베이스 접근
커스텀 도구 추가
서드파티 서비스 연동

MCP 설정 위치


# 글로벌 설정
~/.claude/settings.json
 
# 프로젝트 설정
.claude/settings.json

기본 MCP 설정


{
  "mcpServers": {
    "server-name": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-name"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

인기 MCP 서버

Filesystem 서버

파일 시스템 작업을 위한 MCP 서버입니다.


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

GitHub 서버

GitHub API 통합을 제공합니다.


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

PostgreSQL 서버

PostgreSQL 데이터베이스 접근을 제공합니다.


{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost/db"]
    }
  }
}

Slack 서버

Slack 통합을 제공합니다.


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

MCP 서버 관리

MCP를 너무 많이 활성화하면 컨텍스트 윈도우가 70k로 줄어들 수 있습니다!

권장 설정

항목	권장 수
설정해둘 MCP 수	20-30개
프로젝트당 활성화할 MCP	10개 미만
활성 도구 수	80개 미만

MCP 비활성화

프로젝트별로 불필요한 MCP를 비활성화할 수 있습니다.


{
  "disabledMcpServers": [
    "unused-server-1",
    "unused-server-2"
  ]
}

커스텀 MCP 서버 개발

기본 구조


import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
const server = new Server(
  {
    name: "my-custom-server",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);
 
// 도구 정의
server.setRequestHandler("tools/list", async () => ({
  tools: [
    {
      name: "my_tool",
      description: "My custom tool",
      inputSchema: {
        type: "object",
        properties: {
          query: { type: "string", description: "Search query" }
        },
        required: ["query"]
      }
    }
  ]
}));
 
// 도구 실행
server.setRequestHandler("tools/call", async (request) => {
  if (request.params.name === "my_tool") {
    const { query } = request.params.arguments;
    // 도구 로직 구현
    return {
      content: [{ type: "text", text: `Result for: ${query}` }]
    };
  }
  throw new Error("Unknown tool");
});
 
// 서버 시작
const transport = new StdioServerTransport();
await server.connect(transport);

커스텀 서버 등록


{
  "mcpServers": {
    "my-custom": {
      "command": "node",
      "args": ["/path/to/my-server.js"]
    }
  }
}

MCP 디버깅

서버 로그 확인


# MCP 서버 디버그 모드
MCP_DEBUG=1 claude
 
# 특정 서버 테스트
npx @modelcontextprotocol/server-name --help

연결 문제 해결

서버가 시작되지 않음
- 명령어와 인자 확인
- 필요한 패키지 설치 확인
- 환경 변수 설정 확인
도구가 표시되지 않음
- MCP 서버가 올바르게 시작되었는지 확인
- tools/list 핸들러 구현 확인
인증 오류
- API 키나 토큰 확인
- 환경 변수 이름 확인

보안 고려사항

MCP 서버에 민감한 정보를 전달할 때 주의하세요!

권장 사항

API 키는 환경 변수로 전달
최소 권한 원칙 적용
신뢰할 수 있는 MCP 서버만 사용
정기적으로 MCP 서버 업데이트

환경 변수 사용


{
  "mcpServers": {
    "my-server": {
      "command": "npx",
      "args": ["-y", "my-mcp-server"],
      "env": {
        "API_KEY": "${MY_API_KEY}"
      }
    }
  }
}

유용한 MCP 서버 목록

서버	용도
`@modelcontextprotocol/server-filesystem`	파일 시스템 작업
`@modelcontextprotocol/server-github`	GitHub 통합
`@modelcontextprotocol/server-postgres`	PostgreSQL 접근
`@modelcontextprotocol/server-slack`	Slack 통합
`@modelcontextprotocol/server-brave-search`	Brave 검색
`@modelcontextprotocol/server-puppeteer`	브라우저 자동화