Claude Code MCP 서버 연동하기 ㅡ 설치부터 GitHub DB 연결까지 (Windows 트러블슈팅 포함)

이 글에서 사용하는 주요 용어 정의

용어정의

MCP	AI와 외부 도구를 잇는 개방형 프로토콜
stdio	표준 입출력 스트림 기반 프로세스 통신
.mcp.json	팀원과 도구 설정을 공유하는 설정 파일

외부 도구와 에이전트를 잇는 MCP

Anthropic에 따르면 Claude Code는 MCP로 외부 리소스와 통신하며 도구를 호출합니다. Windows 환경에서 GitHub·DB 연동과 트러블슈팅을 정리합니다.

> 코드 검증 안내: 본문에 수록된 모든 CLI 명령어 및 JSON 설정 코드는 공식 문서 규격에 따라 작성된 미실행 예제 코드이며, 실제 환경에서의 동작을 직접 검증하지 않았습니다. 독자의 환경과 버전에 맞춰 확인 후 사용하시기 바랍니다.

Claude Code MCP 관리 명령어와 설정 구조

설정 스코프는 세 가지로 나뉩니다.

1. local (기본값): 현재 프로젝트 디렉토리에서 사용자 개인 설정으로 저장됩니다. 다른 사용자와 공유되지 않으며, CLI 등록 시 스코프 옵션을 생략하면 기본적으로 이 범위에 저장됩니다.
2. project: .mcp.json에 저장되며 Git으로 팀원과 공유합니다 (--scope project).
3. user: 전역 설정(~/.claude.json)으로 모든 프로젝트에서 공통 사용합니다 (--scope user).

아래 등록 명령은 별도 스코프를 지정하지 않으므로 기본값인 local 스코프로 등록됩니다.

claude mcp add <이름> -- <명령> [인자...]
claude mcp list
claude mcp remove <이름>

세션에서는 /mcp로 도구 확인, /doctor로 진단합니다.

실전 1: GitHub MCP 서버 연동

GitHub MCP 서버를 연동하면 Claude Code가 이슈를 조회하고 코드를 탐색할 수 있습니다.

GitHub에서 repo, read:org 권한 PAT를 발급받아 등록합니다. Windows(PowerShell, CMD)는 npx 실행 시 cmd /c로 감싸야 합니다.

claude mcp add github --env GITHUB_PERSONAL_ACCESS_TOKEN="토큰" -- cmd /c npx -y @modelcontextprotocol/server-github

위 명령은 기본 local 스코프로 등록되므로 토큰 정보가 개인 로컬 환경에만 유지됩니다. 팀원 공유 시 .mcp.json을 작성합니다.

> 보안 주의: .mcp.json은 Git으로 공유되는 파일입니다. 실제 토큰 값을 파일에 직접 입력한 상태로 Git에 커밋하면 인증정보가 외부에 노출될 수 있습니다. 실제 토큰이 포함된 파일은 절대로 Git에 커밋하지 마세요. 개인 인증정보는 기본 local 스코프로 관리하거나 형상관리에서 제외해야 합니다.

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

세션에서 15번 이슈를 확인하고 코드를 수정해 줘와 같이 요청합니다.

실전 2: 데이터베이스 연동 (PostgreSQL & SQLite)

데이터베이스 MCP를 연결하면 테이블 관계와 컬럼 정보를 에이전트가 직접 확인하므로, 스키마를 참고해 모델이나 쿼리 작성을 요청할 수 있습니다.

PostgreSQL은 데이터 오염을 막기 위해 읽기 전용(Read-Only) 계정을 연결합니다. SQLite는 uvx로 연결합니다.

claude mcp add postgres -- cmd /c npx -y @modelcontextprotocol/server-postgres "postgresql://readonly_user:password@localhost:5432/mydb"
claude mcp add sqlite -- uvx mcp-server-sqlite --db-path "C:/workspace/data.db"

연결 후 세션에서 users 테이블 인덱스 구조를 확인하고 조회 성능 개선 방안을 제안해 줘와 같이 질의하면 스키마를 바탕으로 SQL 제안을 요청할 수 있습니다.

Windows 집중 트러블슈팅

Windows 환경에서 MCP 설정 시 자주 발생하는 오류와 해결 방법입니다.

• npx 실행 실패 (Spawn ENOENT): Node.js 공식 문서에 따르면 Windows에서 npx는 실행 파일이 아니라 배치 파일(npx.cmd)입니다. 셸 없이 실행하는 프로세스 특성상 Windows 네이티브 환경(CMD, PowerShell)에서는 cmd /c npx -y <패키지>로 감싸야 실행됩니다. 반면 WSL2(Linux) 환경에서는 일반 바이너리로 동작하므로 cmd /c가 필요하지 않습니다.
• 인자 분리 구분자(--) 누락: claude mcp add와 실행 명령 사이 --가 빠지면 파싱 에러가 납니다. 반드시 -- 뒤에 실행 명령을 적습니다.
• Git Bash 경로 왜곡 방지 (MSYS_NO_PATHCONV=1): Git Bash의 경로 변환으로 인한 URL 왜곡을 막으려면 MSYS_NO_PATHCONV=1을 지정합니다.
• PowerShell 실행 정책 차단: 실행 차단 시 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned를 적용합니다.
• 경로 역슬래시(\) 이스케이프: .mcp.json에서는 역슬래시 대신 슬래시(/)나 \\를 씁니다.

마무리

설정 후 claude mcp list로 연결 상태를 확인합니다. 안전한 local 스코프와 읽기 전용 DB 계정부터 시작해 보시기 바랍니다.

참고 링크

• Claude Code 공식 문서 (MCP 연동 가이드)
• Model Context Protocol 공식 레퍼런스 저장소