MCP 서버 설정

세 가지 설정 스코프

MCP 서버는 목적에 따라 세 가지 위치에 설정할 수 있습니다.

스코프	파일 경로	공유 여부	용도
project	.mcp.json	팀 공유 (Git 포함)	프로젝트 공통 서버
user	~/.claude.json	개인 전역	모든 프로젝트에서 사용
local	.claude/settings.local.json	개인 로컬	개인 오버라이드

// .mcp.json (프로젝트 공유 - Git에 커밋)
{
  "mcpServers": {
    "project-db": {
      "command": "node",
      "args": ["./scripts/mcp-server.js"]
    }
  }
}

// ~/.claude.json (사용자 전역)
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "${HOME}"]
    }
  }
}

stdio 서버 설정

로컬 프로세스를 MCP 서버로 실행하는 가장 일반적인 방식입니다.

{
  "mcpServers": {
    "my-tool": {
      "command": "python3",
      "args": ["/path/to/mcp_server.py", "--port", "8080"],
      "env": {
        "PYTHONPATH": "/path/to/lib",
        "API_KEY": "${MY_API_KEY}",
        "DEBUG": "false"
      }
    }
  }
}

필드	필수	설명
command	예	실행할 명령어
args	아니오	명령어 인수 배열
env	아니오	추가 환경 변수

HTTP/SSE 서버 설정

원격 MCP 서버에 연결할 때 사용합니다.

{
  "mcpServers": {
    "remote-service": {
      "type": "http",
      "url": "https://mcp.myservice.com/v1",
      "headers": {
        "Authorization": "Bearer ${SERVICE_TOKEN}",
        "X-Team-ID": "${TEAM_ID}"
      }
    },
    "event-stream": {
      "type": "sse",
      "url": "https://events.myservice.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer ${SSE_TOKEN}"
      }
    }
  }
}

필드	설명
type	http 또는 sse
url	서버 엔드포인트 URL
headers	HTTP 요청 헤더

환경 변수 확장

설정 파일에서 $VAR 또는 ${VAR} 구문으로 환경 변수를 참조할 수 있습니다. 이 값들은 Claude Code 시작 시 셸 환경에서 확장됩니다.

{
  "mcpServers": {
    "database": {
      "command": "node",
      "args": ["./mcp-db-server.js"],
      "env": {
        "DB_HOST": "${DB_HOST}",
        "DB_PORT": "$DB_PORT",
        "DB_NAME": "${DB_NAME:-myapp}",
        "DB_PASSWORD": "${DB_PASSWORD}"
      }
    }
  }
}

비밀 키나 토큰을 설정 파일에 직접 기입하지 말고 반드시 환경 변수로 관리하세요.

설정 예시 모음

// 파일시스템 서버
{
  "filesystem": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
  }
}

// PostgreSQL 데이터베이스
{
  "postgres": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-postgres"],
    "env": { "POSTGRES_URL": "${DATABASE_URL}" }
  }
}

// GitHub 통합
{
  "github": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-github"],
    "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
  }
}

공식 서버 패키지들은 npm 패키지로 배포되어 npx -y로 즉시 실행할 수 있습니다. 사용 가능한 공식 서버 목록은 modelcontextprotocol.io/servers에서 확인하세요.