GitHub MCP 서버

GitHub MCP Server는 AI 도구를 GitHub 플랫폼에 직접 연결합니다. 이를 통해 AI 에이전트, 어시스턴트 및 챗봇은 레포지토리를 읽고 코드 파일을 관리하며, 이슈와 PR을 관리하고, 코드를 분석하며, 워크플로우를 자동화할 수 있습니다. 모든 것이 자연어 상호작용을 통해 이루어집니다.

사용 사례 (Use Cases)

• 레포지토리 관리 (Repository Management): 접근 가능한 모든 레포지토리에 걸쳐 코드를 탐색하고 쿼리하며, 파일을 검색하고, 커밋을 분석하고, 프로젝트 구조를 이해할 수 있습니다.
• 이슈 및 PR 자동화 (Issue & PR Automation): 이슈와 풀 리퀘스트(PR)를 생성, 업데이트 및 관리합니다. AI가 버그 트리아지(triage), 코드 변경 검토, 프로젝트 보드 유지 관리를 돕도록 할 수 있습니다.
• CI/CD 및 워크플로우 인텔리전스 (CI/CD & Workflow Intelligence): GitHub Actions 워크플로우 실행을 모니터링하고, 빌드 실패를 분석하며, 릴리스를 관리하고, 개발 파이프라인에 대한 통찰력을 얻습니다.
• 코드 분석 (Code Analysis): 보안 발견 사항을 검토하고, Dependabot 알림을 검토하며, 코드 패턴을 이해하고, 코드베이스 전반에 걸쳐 포괄적인 통찰력을 얻습니다.
• 팀 협업 (Team Collaboration): 토론에 접근하고, 알림을 관리하며, 팀 활동을 분석하고, 팀의 프로세스를 간소화할 수 있습니다.

단순한 자연어 쿼리부터 복잡한 다단계 에이전트 워크플로우까지, AI 도구를 GitHub의 컨텍스트 및 기능과 연결하려는 개발자를 위해 구축되었습니다.

Go 모듈 사용하기 (Using the Go module)

Go 모듈 경로는 github.com/github/github-mcp-server/v2입니다. 라이브러리 소비자들은 임포트 시, 예를 들어 github.com/github/github-mcp-server/v2/pkg/github와 같이 이 접두사를 사용해야 하며, go get 명령어에서도 사용해야 합니다. 레포지토리 체크아웃에서 빌드할 때는 /v2 하위 디렉토리가 필요하지 않습니다.

기존의 v2.0.0 태그는 이 모듈 경로 수정보다 앞서 생성되었기 때문에 Go 모듈로 사용할 수 없습니다. 이 변경 사항이 병합된 후에는, 올바른 모듈 경로를 포함하는 커밋에서 v2.0.1과 같은 새로운 릴리스가 태그되어야 합니다. 그때까지 소비자들은 이 변경 사항을 포함하는 커밋의 가상 버전(pseudo-version)을 사용할 수 있습니다.

원격 GitHub MCP 서버 (Remote GitHub MCP Server)

원격 GitHub MCP 서버는 GitHub에서 호스팅하며 가장 쉽게 사용할 수 있는 방법을 제공합니다. 만약 사용 중인 MCP 호스트가 원격 MCP 서버를 지원하지 않아도 걱정할 필요 없습니다! 대신 GitHub MCP 서버의 로컬 버전을 사용할 수 있습니다.

필수 조건 (Prerequisites)

1. 원격 서버 지원이 가능한 호환 MCP 호스트 (VS Code 1.101 이상, Claude Desktop, Cursor, Windsurf 등)
2. 적용 가능한 정책 활성화

VS Code에 설치하기 (Install in VS Code)

빠른 설치를 위해 위에 있는 원클릭 설치 버튼 중 하나를 사용하세요. 해당 절차를 완료한 후, 에이전트 모드(Copilot Chat 텍스트 입력창 옆에 위치)를 토글하면 서버가 시작됩니다. 원격 MCP 및 OAuth 지원을 위해서는 VS Code 1.101 또는 그 이후 버전을 사용하고 있는지 확인하세요.

대안으로, VS Code를 수동으로 구성하려면 아래 예시에서 적절한 JSON 블록을 선택하여 호스트 설정에 추가하세요:

다른 MCP 호스트에 설치하기 (Install in other MCP hosts)

• Copilot CLI - GitHub Copilot CLI 설치 가이드
• GitHub Copilot in other IDEs - GitHub Copilot을 JetBrains, Visual Studio, Eclipse, Xcode 등 다른 IDE에 설치하는 방법
• Claude Applications - Claude Desktop 및 Claude Code CLI 설치 가이드
• Codex - OpenAI Codex 설치 가이드
• Cursor - Cursor IDE 설치 가이드
• OpenCode - OpenCode 터미널 에이전트 설치 가이드
• Windsurf - Windsurf IDE 설치 가이드
• Zed - Zed 에디터 설치 가이드
• Rovo Dev CLI - Rovo Dev CLI 설치 가이드

참고: 각 MCP 호스트 애플리케이션은 OAuth를 통해 원격 액세스를 지원하려면 GitHub App 또는 OAuth App을 구성해야 합니다. 원격 MCP 서버를 지원하는 모든 호스트 애플리케이션은 PAT 인증을 사용하여 원격 GitHub 서버를 지원해야 합니다. 구성 세부 정보 및 지원 수준은 호스트마다 다릅니다. 더 자세한 내용은 해당 호스트 애플리케이션의 문서를 참조하십시오.

설정 (Configuration)

툴셋 설정 (Toolset configuration)

원격 서버 구성, 툴셋, 헤더 및 고급 사용에 대한 전체 세부 정보는 Remote Server Documentation를 참조하십시오. 이 파일은 VS Code 및 기타 MCP 호스트에서 원격 GitHub MCP 서버를 연결하고 사용자 정의하며 설치하기 위한 포괄적인 지침과 예제를 제공합니다.

툴셋이 지정되지 않은 경우, 기본 툴셋이 사용됩니다.

Insiders 모드 (Insiders Mode)

새로운 기능을 일찍 경험하세요! 원격 서버는 새로운 기능과 실험적인 도구에 대한 조기 액세스를 제공하는 인사이더 버전을 제공합니다.

{
  "servers": {
    "github": {
...

{
  "servers": {
    "github": {
...

더 많은 세부 정보와 예시는 원격 서버 문서를 참조하고, 사용 가능한 전체 목록은 Insiders 기능을 참고하세요.

GitHub Enterprise

데이터 상주(data residency)가 적용된 GitHub Enterprise Cloud (ghe.com)

GitHub Enterprise Cloud 역시 원격 서버를 사용할 수 있습니다.

GitHub PAT 토큰을 사용하여 https://octocorp.ghe.com의 예시:

{
    ...
    "github-octocorp": {
...

참고: VS Code 및 GitHub Copilot에서 GitHub Enterprise를 사용하는 OAuth 방식을 사용할 때는, VS Code 설정도 GitHub Enterprise 인스턴스를 가리키도록 구성해야 합니다. VS Code에서 인증하기를 참조하세요.

GitHub Enterprise Server

GitHub Enterprise Server는 원격 서버 호스팅을 지원하지 않습니다. 로컬 서버 구성에서 GitHub Enterprise Server 및 데이터 상주가 적용된 Enterprise Cloud (ghe.com)를 참조해 주십시오.

로컬 GitHub MCP 서버

사전 요구 사항

1. 컨테이너에서 서버를 실행하려면 Docker가 설치되어 있어야 합니다.
2. Docker가 설치되면, Docker가 실행 중인지도 확인해야 합니다. Docker 이미지는 ghcr.io/github/github-mcp-server에서 사용할 수 있습니다. 이 이미지는 공개(public)이며, 풀(pull) 시 오류가 발생하면 토큰이 만료되었을 수 있으므로 docker logout ghcr.io를 실행해야 할 수도 있습니다.
3. 인증. github.com에서는 미리 아무것도 생성할 필요가 없습니다. 위에 있는 원클릭 버튼들은 첫 사용 시 OAuth로 로그인하며(브라우저 기반 흐름이며, 토큰은 메모리에만 유지됩니다), Docker 버튼들은 고정된 콜백 포트(127.0.0.1:8085)를 게시하여 컨테이너의 로그인 콜백이 도달 가능하도록 합니다. 작동 방식, 헤드리스/디바이스 코드 폴백(fallback), 그리고 자체 OAuth 또는 GitHub App을 가져오는 방법은 **Local Server OAuth Login**을 참조하십시오 (GitHub Enterprise Server 및 ghe.com의 경우 필수).

토큰을 선호하시나요? 대신 GITHUB_PERSONAL_ACCESS_TOKEN을 설정하여 GitHub Personal Access Token으로 인증할 수 있습니다 (OAuth보다 우선합니다). MCP 서버는 GitHub API의 많은 부분을 사용할 수 있으므로, AI 도구에 부여하기 편안하다고 느끼는 권한만 활성화하세요 (액세스 토큰에 대한 자세한 내용은 문서를 확인해 주세요).

환경 변수 (권장)

GitHub PAT를 안전하게 보관하고 여러 MCP 호스트에서 재사용하려면:

1. PAT를 환경 변수에 저장합니다

   복사

   export GITHUB_PAT=your_token_here
   

   1

   2

   또는 .env 파일을 생성합니다:

   복사

   GITHUB_PAT=your_token_here
   

   1

   2

2. .env 파일 보호하기

   복사

   # 실수로 커밋되는 것을 방지하려면 .gitignore에 추가하세요
   echo ".env" >> .gitignore
   

   1

   2

   3

3. 설정에서 토큰 참조하기

   복사

   # CLI 사용법
   claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=$GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
   

   1

   2

   3

...

> **참고**: 환경 변수 지원은 호스트 앱 및 IDE에 따라 다릅니다. Windsurf와 같은 일부 애플리케이션은 설정 파일에 하드코딩된 토큰을 요구합니다.

### 토큰 보안 모범 사례

- **최소 범위(Minimum scopes)**: 필요한 권한만 부여하세요
- `repo` - 리포지토리 작업
- `read:packages` - Docker 이미지 접근
- `read:org` - 조직 팀 접근
- **별도 토큰 사용**: 프로젝트/환경마다 다른 PAT를 사용하세요
- **정기적인 순환(Regular rotation)**: 주기적으로 토큰을 업데이트하세요
- **절대 커밋하지 않기**: 토큰은 버전 관리에서 분리하세요
- **파일 권한**: 토큰이 포함된 설정 파일에 대한 접근을 제한하세요

```bash
chmod 600 ~/.your-app/config.json

데이터 거주지(data residency)를 갖춘 GitHub Enterprise Server 및 Enterprise Cloud (ghe.com)

플래그 --gh-host와 환경 변수 GITHUB_HOST를 사용하여 데이터 거주지를 갖춘 GitHub Enterprise Server 또는 GitHub Enterprise Cloud의 호스트 이름을 설정할 수 있습니다.