GitHub MCP Server 배포 방법: Windows·Linux·macOS 전 플랫폼 가이드

Cursor에서 Agent가 Issue 조회, PR 생성, 저장소 파일 읽기를 하게 하고 싶은데—「어떤 GitHub MCP Server를 설치해야 하지?」에서 막힙니다. npm의 구 패키지는 이미 폐기되었고, 온라인 튜토리얼마다 말이 다릅니다. 이 글은 GitHub 공식 저장소 github/github-mcp-server(2026-07-31 기준 최신 v1.7.0)를 기준으로 원격 호스팅, Docker 로컬, 사전 빌드 바이너리, 소스 컴파일 네 가지 경로를 정리합니다. Windows / Linux / macOS에서 그대로 따라 하면 됩니다.

다루는 내용: PAT 발급, 플랫폼별 설정 파일 경로, Cursor / Claude Desktop / VS Code Copilot 연동 예시, 7단계 검수 체크리스트. 비공식 서드파티 Server 구현은 다루지 않습니다.

---

Quick Answer: 네 가지 배포 방식 선택

아래 표를 보고 30초 안에 경로를 정하세요. 대부분의 개인 개발자는 방식 1(원격 호스팅)부터 시작하고, 사내망이나 자격 증명 격리가 필요한 팀은 방식 2(Docker)를 고려하세요.

배포 전 준비: PAT, 호스트 앱 및 설정 경로

1. GitHub Personal Access Token 발급

GitHub → Settings → Personal access tokens에서 Fine-grained 또는 Classic PAT를 만드세요. 자주 쓰는 scope:

• repo — 저장소 내용, 브랜치, 커밋 읽기/쓰기
• read:org — 조직 및 팀 정보 읽기
• Agent가 수행할 범위에 따라 read:project, workflow 등을 추가

2. MCP 호스트 앱 및 설정 파일 경로

클라이언트마다 MCP 설정 위치가 다릅니다. 아래 표는 OS별 대표 경로입니다—JSON 수정 후 보통 완전 재시작이 필요합니다. 일부 편집기는 저장 시 JSON을 자동 포맷하므로, PAT를 env에 넣었다면 포맷 후에도 따옴표와 쉼표가 유효한지 확인하세요.

팀이 MCP 연동 테스트용 격리된 Mac 환경이 필요하다면(PAT가 개인 노트북에 남지 않도록) Macstripe Cloud Mac을 전용 테스트 노드로 빌려 SSH로 접속해 Docker나 바이너리를 설정하고, 로컬 Cursor와 stdio/원격 터널로 연결하세요.

방식 1: 원격 호스팅 Server(전 플랫폼 동일)

GitHub 공식 원격 MCP 엔드포인트: https://api.githubcopilot.com/mcp/. Windows, Linux, macOS에서 설정이 동일하다는 점이 큰 장점입니다—로컬 프로세스나 Docker가 필요 없습니다.

인증: HTTP 요청 헤더에 Authorization: Bearer <YOUR_GITHUB_PAT>를 포함합니다. 원격 Server JSON 필드명은 클라이언트마다 약간 다르며, 아래는 Cursor와 VS Code의 일반적인 패턴입니다.

Cursor / VS Code 설정 예시

~/.cursor/mcp.json(또는 프로젝트 .cursor/mcp.json)을 편집하세요:

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

저장 후 Cursor를 완전히 종료하고 재시작하세요. Settings → MCP에서 github가 녹색 Connected인지 확인합니다. 첫 연결 시 권한 프롬프트가 뜨면 클라이언트 안내를 따르세요.

원격 호스팅에서는 GitHub가 Server 업그레이드와 보안 패치를 담당합니다—PAT 수명만 관리하면 됩니다. 기업망에서 아웃바운드 HTTPS가 프록시되는 경우 시스템 또는 클라이언트에 HTTPS_PROXY를 설정해 api.githubcopilot.com에 접근 가능하게 하세요. 터미널에서 연결을 테스트할 수 있습니다:

curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer ghp_xxxxxxxxxxxxxxxxxxxx" \
  https://api.githubcopilot.com/mcp/

200 또는 405(Method Not Allowed—엔드포인트 도달 가능)이면 네트워크와 Token 기본은 정상입니다. 401이면 PAT 만료 또는 scope 부족을 확인하세요.

방식 2: Docker 로컬 배포

공식 이미지: ghcr.io/github/github-mcp-server. 로컬 Docker는 자격 증명 격리, 오프라인 실행, 커스텀 네트워크 정책이 필요한 팀에 적합합니다. 이미지는 PAT와 OAuth 인증을 모두 지원합니다.

플랫폼별 Docker 사전 준비

• Windows: Docker Desktop을 설치하고 WSL2 백엔드를 활성화한 뒤 docker version이 정상인지 확인하세요. Docker Desktop → Settings → Resources에서 최소 2GB RAM을 할당해 컨테이너 시작 시 OOM을 피하세요.
• macOS: Docker Desktop for Mac을 설치하세요(Apple Silicon은 ARM 이미지를 자동으로 가져옵니다). Rosetta로 Intel Docker를 쓰는 경우 올바른 아키텍처 레이어를 pull하는지 확인하세요.
• Linux: Docker Engine을 설치하고(sudo apt install docker.io 등) 사용자를 docker 그룹에 추가한 뒤 재로그인하세요—그렇지 않으면 매번 sudo docker가 필요합니다.

세 플랫폼 모두 mcp.json 내용이 동일합니다—바이너리 대비 Docker의 또 다른 장점: 한 번 작성해 팀 내 Windows / macOS / Linux에서 재사용할 수 있습니다.

PAT 모드 — mcp.json 설정

Docker는 환경 변수 GITHUB_PERSONAL_ACCESS_TOKEN으로 PAT를 받습니다:

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

OAuth 모드 — 콜백 포트 매핑

OAuth 흐름에서는 컨테이너 콜백 포트를 호스트 127.0.0.1:8085에 매핑하고 GITHUB_OAUTH_CALLBACK_PORT=8085를 설정하세요:

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

첫 연결 시 브라우저에서 GitHub 권한 페이지가 열립니다. 승인 후 Server가 Token을 관리하므로 JSON에 PAT를 넣을 필요가 없습니다.

Docker 이미지 pull 확인

docker pull ghcr.io/github/github-mcp-server
docker run --rm ghcr.io/github/github-mcp-server --version

팀이 격리된 원격 Mac(예: Macstripe Cloud 노드)에서 MCP Server를 실행하면 Windows 개발자는 SSH 터널로 stdio를 로컬 Cursor에 전달할 수 있습니다—개인 PC에 PAT를 노출하지 않으면서 macOS 측 환경 일관성을 유지합니다. MCP 보안 및 운영 모범 사례는 AGNTCon MCP 배포 가이드를 참고하세요.

방식 3: 사전 빌드 바이너리

Docker 없이 GitHub Releases에서 사전 빌드 패키지를 다운로드하세요(v1.7.0부터 제공):

macOS / Linux 설치 및 PATH

# macOS ARM 예시
tar -xzf github-mcp-server_Darwin_arm64.tar.gz
sudo mv github-mcp-server /usr/local/bin/
chmod +x /usr/local/bin/github-mcp-server
github-mcp-server --version

Windows install

# PowerShell
Expand-Archive github-mcp-server_Windows_x86_64.zip -DestinationPath C:\Tools\github-mcp-server
# C:\Tools\github-mcp-server를 시스템 PATH에 추가

mcp.json 설정(stdio 모드)

{
  "mcpServers": {
    "github": {
      "command": "github-mcp-server",
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Windows에서 PATH가 적용되지 않으면 절대 경로를 사용하세요: "command": "C:\\Tools\\github-mcp-server\\github-mcp-server.exe".

바이너리는 빠르게 시작하고 Docker 데몬이 필요 없습니다. 대신 버전 업그레이드는 수동입니다. 팀은 사용 중인 버전(예: v1.7.0)과 체크섬을 문서화해 구성원마다 Server 버전이 달라 도구 동작이 어긋나지 않게 하세요.

방식 4: 소스 컴파일(고급)

커스텀 브랜치, PR 기여, 전체 소스 감사가 필요할 때 공식 저장소에서 빌드하세요. Go 1.24+가 필요합니다.

git clone https://github.com/github/github-mcp-server.git
cd github-mcp-server
git checkout v1.7.0   # 또는 main
go build -o github-mcp-server ./cmd/github-mcp-server
./github-mcp-server --version

방식 3과 동일하게 사용하며 mcp.json의 command를 빌드 결과물 경로로 지정하세요. 운영 환경에서는 main 대신 릴리스 태그(예: v1.7.0)를 고정하세요.

소스 빌드는 github/github-mcp-server에 PR을 올리는 기여자, 코드를 감사한 뒤 내부 패치를 배포하는 보안 팀에 적합합니다. 커스터마이징이 없다면 방식 1 또는 2로 충분하며 Go 툴체인이 필요 없습니다.

주요 MCP 호스트 연동: Cursor, Claude Desktop, VS Code Copilot

JSON 구조는 클라이언트마다 약간 다르지만 모두 mcpServers 항목을 선언합니다. 아래는 가장 흔한 패턴입니다(Docker PAT 모드; 원격 호스팅은 command/args를 url + headers로 교체).

Cursor

전역: ~/.cursor/mcp.json, 프로젝트: .cursor/mcp.json. 프로젝트 설정은 해당 저장소만 GitHub MCP가 필요할 때 적합합니다—예: 사이드 프로젝트와 다른 PAT를 쓰는 오픈소스 기여. 재시작 후 채팅에서 「내 GitHub 저장소 목록」을 요청하세요. Agent가 GitHub 도구가 없다고 하면 MCP가 로드되지 않은 것이므로 MCP 패널 로그를 확인하세요.

Claude Desktop

플랫폼에 맞는 claude_desktop_config.json을 편집하세요. 구조는 Cursor와 같고 최상위 키도 mcpServers입니다:

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

저장 후 Claude Desktop을 종료했다가 다시 여세요. macOS에서는 메뉴 막대 아이콘 → Settings → Developer에서 MCP 연결 로그를 확인할 수 있습니다.

VS Code Copilot(Agent 모드)

VS Code 1.99+에서 Copilot Chat은 MCP를 지원합니다. Command Palette → MCP: Add Server를 열거나 작업 영역에 .vscode/mcp.json을 만드세요. 원격 호스팅 설정은 Cursor와 동일합니다.

Cursor와 Claude Code 중 무엇을 쓸지 모르겠다면 MCP 호스트를 정하기 전에 AI 코딩 도구 비교를 참고하세요.

7단계 검수 체크리스트 및 장애 대응

설정 후 아래 체크리스트를 따라 Agent가 실제로 GitHub 도구를 호출하는지 확인하세요.

• 1단계: PAT 생성 및 repo scope(필요 시 read:org 등) 포함
• 2단계: mcp.json JSON 문법 유효(jq . 또는 온라인 검증기 사용)
• 3단계: 클라이언트 완전 재시작(창만 닫은 것이 아님)
• 4단계: MCP 패널에서 github가 Connected / 녹색
• 5단계: 채팅에서 「내 GitHub 저장소 목록」 요청 시 실제 저장소명 반환
• 6단계: 비공개 저장소 파일 읽기로 PAT 권한 확인
• 7단계: 클라이언트 로그에 401 Unauthorized 또는 connection refused 없음

자주 발생하는 문제

예전 인식: 「npm 패키지 설치하면 GitHub 연결 끝.」
2025년 4월부터 공식 경로는 github/github-mcp-server; 원격 호스팅은 api.githubcopilot.com/mcp/—server-github를 더 이상 찾지 마세요.

자주 묻는 질문

원격 호스팅과 Docker 로컬 배포 중 무엇을 선택해야 하나요?

개인 체험이나 팀 빠른 검증에는 GitHub 원격 호스팅(https://api.githubcopilot.com/mcp/)을 우선하세요—전 플랫폼 동일 설정, 프로세스 유지 불필요. 오프라인 실행, 커스텀 도구 세트, 엄격한 자격 증명 격리가 필요하면 Docker 로컬(ghcr.io/github/github-mcp-server)을 선택하세요.

npm의 @modelcontextprotocol/server-github를 계속 쓸 수 있나요?

아니요. 해당 npm 패키지는 2025년 4월 폐기되었습니다. GitHub 공식 저장소 github/github-mcp-server(현재 최신 v1.7.0)를 사용하세요.

PAT에 어떤 scope가 필요한가요?

Fine-grained 또는 Classic PAT에는 최소 repo(저장소 읽기/쓰기)와 read:org(조직 정보 읽기)가 필요합니다. Agent가 호출할 도구에 따라 Issues, Pull Requests, Projects용 scope를 추가하세요.

Windows에서 Docker 이미지 pull이 실패하면?

Docker Desktop이 실행 중이고 WSL2 백엔드가 정상인지 확인하세요. Settings → Resources에서 충분한 메모리를 할당하고 docker login ghcr.io 후 docker pull ghcr.io/github/github-mcp-server를 다시 시도하세요.

Cursor에서 mcp.json을 수정했는데 반영되지 않아요

JSON 저장 후 Cursor를 완전히 종료하고 재시작하세요. ~/.cursor/mcp.json과 프로젝트 .cursor/mcp.json 충돌 확인(프로젝트 우선); Settings → MCP에서 연결 상태와 오류 로그를 확인하세요.

마무리

GitHub MCP Server 공식 배포 경로는 명확합니다:

1. 가장 빠른 시작 — 원격 호스팅 https://api.githubcopilot.com/mcp/ + PAT, 전 플랫폼 동일 JSON
2. 로컬 제어 — Docker 이미지 ghcr.io/github/github-mcp-server, PAT 또는 OAuth
3. Docker 없이 — Releases에서 사전 빌드 바이너리 다운로드, PATH 설정
4. 고급 커스터마이징 — Go 1.24+ 소스 빌드, 운영에 릴리스 태그 고정

Cursor에서 원격 호스팅으로 「저장소 목록 → 파일 읽기 → Issue 조회」까지 먼저 확인하세요. PAT scope가 맞으면 Docker 또는 격리된 원격 Mac 환경으로 옮길지 결정하세요.

팀은 MCP 설정 파일(PAT 평문 제거)을 버전 관리하고 환경 변수나 시크릿 관리로 Token을 주입하세요—MCP 안전 배포 모범 사례와 같습니다. Windows 개발자가 iOS 빌드와 Agent 워크플로도 필요하면 Macstripe Cloud Mac을 일 단위로 빌릴 수 있습니다—약 5분 내 SSH 개통, MCP Server·Xcode·Fastlane을 같은 macOS 노드에 두고 노트북은 원격 터미널로 사용. 개인 PC에서 Docker와 원격 Xcode 플러그인을 섞는 것보다 훨씬 안정적입니다.

더 읽어보기

• AGNTCon MCPCon Europe 2026 MCP 배포 가이드 →
• Claude Code vs Cursor vs Codex: AI 코딩 도구 비교 2026 →
• iOS CI 느리고 GitHub Actions 대기? Cloud Mac으로 해결 →