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 | 브라우저 자동화 |