GitHub MCP Server 배포 방법: Windows, Linux, macOS 전 플랫폼 튜토리얼

GitHub MCP Server는 GitHub이 공식 유지보수하는 Model Context Protocol 서버로, Cursor, Claude Desktop, VS Code Copilot 등 AI 호스트가 표준화된 도구 호출을 통해 GitHub REST / GraphQL API에 접근할 수 있게 합니다. 저장소 조회, Issue 읽기, PR 생성, 코드 검색 등을 채팅에서 gh 명령 출력을 반복해서 붙여넣지 않아도 됩니다.

이 글은 「먼저 방식 선택 → 환경 설치 → IDE 연동」 순서로 Windows, Linux, macOS 세 가지 설치 경로를 다루며, 바로 복사해 쓸 수 있는 설정 스니펫과 문제 해결 체크리스트를 함께 제공합니다.

2025년 4월부터 커뮤니티 초기 npm 패키지 @modelcontextprotocol/server-github는 폐기되었습니다. 현재 공식 지원되는 유일한 로컬 이미지는 ghcr.io/github/github-mcp-server이며, 원격 호스팅 엔드포인트는 https://api.githubcopilot.com/mcp/입니다.

배포 방식 선택하기

소프트웨어를 설치하기 전에 아래 표를 참고해 어떤 경로를 택할지 먼저 정하세요.

세 방식 모두 인증 로직은 동일합니다. Personal Access Token(PAT)을 설정하거나, 로컬 Docker / 바이너리 모드에서 OAuth 브라우저 로그인을 사용합니다(OAuth token은 메모리에만 유지되고 디스크에 저장되지 않음).

공통 사전 준비

어떤 경로를 선택하든 아래 네 단계를 먼저 완료하는 것을 권장합니다.

1. GitHub PAT 생성
   Fine-grained PAT 생성 페이지를 열고, 사용할 도구에 맞게 권한을 선택하세요. 저장소 읽기 전용 탐색에는 보통 Contents: Read, Metadata: Read가 필요합니다. PR / Issue 생성이 필요하면 쓰기 권한을 추가하세요.

2. 호스트 버전 확인
   - Cursor: 원격 Streamable HTTP는 v0.48.0 이상에서 지원
   - Claude Desktop / VS Code: 각 MCP 문서 참고

3. (로컬 Docker 방식) Docker 설치 및 실행
   - Windows / macOS: Docker Desktop
   - Linux: Docker Engine 설치 후 현재 사용자를 docker 그룹에 추가

4. 이미지 사전 pull(선택이지만 권장)

docker pull ghcr.io/github/github-mcp-server

pull 시 unauthorized 오류가 나면 docker logout ghcr.io 후 다시 시도하세요. 만료된 ghcr 로그인 세션이 원인인 경우가 있습니다.

방식 1: 원격 호스팅(가장 간편)

GitHub은 https://api.githubcopilot.com/mcp/에서 호스팅 MCP 엔드포인트를 제공하며, 로컬에 Docker가 필요 없습니다. Linux 서버, Windows 경량 환경, 또는 회사 정책상 컨테이너 실행이 금지된 경우에 적합합니다.

Cursor 설정 예시

전역 설정 ~/.cursor/mcp.json(Windows 경로: %USERPROFILE%\.cursor\mcp.json)을 편집합니다.

{
  "mcpServers": {
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer YOUR_GITHUB_PAT"
      }
    }
  }
}

YOUR_GITHUB_PAT를 실제 token으로 바꾼 뒤 저장하고 Cursor를 완전히 재시작하세요. Settings → Tools & Integrations → MCP Tools에서 녹색 온라인 표시가 보여야 합니다. Composer에서 「내 GitHub 저장소 목록 보여줘」라고 물어보면 동작을 확인할 수 있습니다.

주의사항

• 원격 모드는 현재 PAT 인증이 주류입니다. 일부 호스트의 OAuth 지원은 아직 보완 중입니다.
• 회사 프록시 / 방화벽에서 api.githubcopilot.com으로의 HTTPS 아웃바운드를 허용해야 합니다.
• PAT를 버전 저장소에 커밋하지 마세요. 프로젝트 수준 설정에 .cursor/mcp.json을 쓸 때는 .gitignore에 추가하세요.

방식 2: Docker 로컬 배포(공식 권장)

Docker 방식은 stdio로 호스트와 통신합니다. 호스트가 docker run -i ...를 실행하고, 컨테이너 내 프로세스가 표준 입출력을 읽고 씁니다. Claude Desktop, Windsurf, Cursor의 원클릭 설치 버튼 뒤에 있는 기본 명령이기도 합니다.

macOS 설치 단계

1. Docker Desktop for Mac 설치(Apple Silicon은 ARM64 버전 선택).
2. 메뉴 막대 고래 아이콘이 Running 상태인지 확인.
3. 터미널에서 검증:

docker run --rm ghcr.io/github/github-mcp-server --help

4. ~/.cursor/mcp.json에 작성:

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GITHUB_PERSONAL_ACCESS_TOKEN",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

Linux 설치 단계

1. 배포판에 맞게 Docker Engine 설치(Ubuntu 예: sudo apt install docker.io).
2. 매번 sudo 없이 쓰려면 사용자를 docker 그룹에 추가:

sudo usermod -aG docker "$USER"
newgrp docker

3. Docker 데몬이 실행 중인지 확인: sudo systemctl enable --now docker.
4. MCP 설정은 macOS와 완전히 동일합니다. ~/.cursor/mcp.json 경로도 같습니다.

GUI 없는 Linux 서버에서 설정 파일에 PAT를 평문으로 쓰고 싶지 않다면 환경 변수 주입을 사용할 수 있습니다.

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"

그다음 mcp.json의 env 블록에서 같은 이름의 변수를 참조합니다(일부 호스트는 ${env:GITHUB_PERSONAL_ACCESS_TOKEN} 문법을 지원하며, 호스트 문서를 기준으로 하세요).

Windows 설치 단계

1. Docker Desktop for Windows 설치.
   - WSL 2 백엔드 권장(Settings → General → Use WSL 2 based engine).
2. Docker Desktop 트레이 아이콘이 실행 중인지 확인.
3. 설정 파일 경로: %USERPROFILE%\.cursor\mcp.json.
4. JSON 내용은 macOS와 동일합니다. command는 여전히 docker입니다(Docker Desktop이 CLI를 PATH에 추가함).

Windows에서 흔한 함정: WSL에서는 docker가 동작해도 Windows 호스트의 Cursor는 Windows 쪽 mcp.json을 읽습니다. 양쪽 설정을 섞지 마세요. Cursor가 Windows에 설치되어 있고 프로젝트는 WSL에 있다면 Windows 사용자 디렉터리에서 MCP를 설정하는 것이 우선입니다.

OAuth 로그인(PAT 수동 입력 생략)

공식 이미지에는 OAuth 앱 자격 증명이 내장되어 있습니다. Docker 모드에서는 콜백 포트를 로컬 루프백 주소에 매핑해야 합니다.

{
  "mcpServers": {
    "github": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "127.0.0.1:8085:8085",
        "-e", "GITHUB_OAUTH_CALLBACK_PORT",
        "ghcr.io/github/github-mcp-server"
      ],
      "env": {
        "GITHUB_OAUTH_CALLBACK_PORT": "8085"
      }
    }
  }
}

첫 연결 시 브라우저가 열려 GitHub 로그인을 완료합니다. token은 메모리에만 저장되며, 컨테이너가 종료되면 무효화됩니다. 헤드리스 서버는 공식 문서의 device code 폴백 절차를 참고하세요.

방식 3: Go 소스 빌드(Docker 없음)

Docker를 설치할 수 없거나 toolset을 잘라 일부 API 기능만 노출해야 하는 경우에 적합합니다.

세 플랫폼 공통 단계

사전 요구: Go 1.24+ 설치.

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
go build -o github-mcp-server cmd/github-mcp-server/main.go

빌드 산출물 이름은 자유롭게 정할 수 있습니다. 아래에서는 ./github-mcp-server를 예로 듭니다.

PAT로 시작(stdio 모드):

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxx"
./github-mcp-server stdio

Cursor에 로컬 바이너리 연결:

{
  "mcpServers": {
    "github": {
      "command": "/绝对路径/github-mcp-server",
      "args": ["stdio"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_PAT"
      }
    }
  }
}

업그레이드 시 git pull && go build만 다시 실행하면 됩니다. Docker 이미지 릴리스를 기다릴 필요가 없습니다.

다른 IDE 및 CLI 연동

설정 키 이름은 호스트마다 다르지만 Docker 명령줄 핵심은 동일합니다.

docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

• Claude Desktop: claude_desktop_config.json의 mcpServers 블록 구조가 Cursor와 같습니다.
• VS Code Copilot: 원격 + 로컬 모두 지원하며, 로컬은 Docker 이미지를 권장합니다.
• Claude Code CLI: 컨테이너 오버헤드를 줄이기 위해 경량 바이너리 방식을 선호합니다.

호스트별 전체 예시는 공식 저장소 docs/installation-guides/ 디렉터리를 참고하세요.

보안 및 운영 권장사항

1. 최소 권한 PAT: toolset에 맞게 권한을 부여하고 정기적으로 교체하세요.
2. 설정 파일 권한: chmod 600 ~/.cursor/mcp.json(Linux / macOS).
3. 읽기 전용 모드: 시작 인자로 read-only를 켜 AI가 저장소를 잘못 수정하는 것을 방지할 수 있습니다.
4. 기업용 GitHub Enterprise Server: OAuth App / GitHub App을 직접 구성해야 하며 github.com 기본 OAuth 자격 증명은 사용할 수 없습니다. 공식 docs/oauth-login.md를 참고하세요.

플랫폼별 차이 보충 설명

경로 및 환경 변수

~/.cursor/mcp.json

macOS와 Linux의 전역 MCP 설정입니다. Windows에서는 %USERPROFILE%\.cursor\mcp.json에 해당합니다.

GITHUB_PERSONAL_ACCESS_TOKEN

Docker / 바이너리 모드에서 PAT 환경 변수 이름입니다. 설정 시 OAuth 흐름보다 우선합니다.

GITHUB_OAUTH_CALLBACK_PORT

OAuth 브라우저 콜백 수신 포트이며, Docker 환경에서는 보통 8085로 고정합니다.

단축키 및 관습적 사용법

Cursor Composer에서는 Cmd+Shift+P(Windows는 Ctrl+Shift+P)로 명령 팔레트를 열고 MCP 관련 설정을 검색할 수 있습니다. 초기에는 npx @modelcontextprotocol/server-github 한 줄 명령으로 서비스를 띄우는 방식이 흔했지만, 이 방식은 폐기되었으므로 이 글의 Docker 또는 원격 엔드포인트 방식을 사용하세요.

프로덕션 환경에서는 PAT를 환경 변수나 시크릿 관리자에 두고, git으로 추적되는 프로젝트 파일에 넣지 마세요.

검증 체크리스트(배포 전)

1. MCP 패널 녹색 표시
2. 도구 목록에 github_* 접두사 항목 표시
3. 읽기 전용 작업(예: 저장소 목록) 호출 성공

로그 위치 안내

Cursor 로그는 Help → Toggle Developer Tools → Console에서 MCP 키워드로 필터링해 볼 수 있습니다. Claude Desktop 로그 경로는 플랫폼마다 다르며, 공식 troubleshooting 장에 전체 목록이 있습니다.

문제 해결 빠른 참조

로컬 빠른 자가 점검: 터미널에서 Docker 명령을 수동 실행해 stderr에 즉시 오류가 나는지 확인한 뒤, IDE 로그의 MCP 시작 명령과 일치하는지 비교하세요.

요약

• 가장 빨리 쓰려면: 원격 https://api.githubcopilot.com/mcp/ + PAT, Cursor v0.48+에서 url로 직접 설정.
• 안정적이고 재현 가능하게: 세 플랫폼 공통 docker run -i --rm ... ghcr.io/github/github-mcp-server.
• 극도로 가볍게 또는 커스터마이징: go build로 바이너리 생성 후 stdio 연동.

배포가 끝나면 AI 대화에서 자연어로 GitHub을 다루는 것이 MCP의 진짜 시간 절약 포인트입니다. 예를 들어 「kvmkit 저장소의 최근 open issue 5개 요약해줘」처럼 말하면 됩니다. CI/CD 파이프라인을 함께 구축하거나 7×24 클라우드 Mac 빌드 노드가 필요하다면, MCP 보조 개발과 자동화 배포를 같은 툴체인에서 통합해 계획할 수 있습니다.

자주 묻는 질문