GitHub MCP 서버: AI와 GitHub 연동하기

GitHub에서 이슈를 만들고 PR을 열고 코드를 검색하는 일은 개발자의 일상이죠. 그런데 이런 반복 작업을 AI에게 시키면 어떨까요?

MCP(Model Context Protocol)가 AI와 외부 시스템을 연결하는 표준으로 자리 잡으면서 GitHub도 공식 MCP 서버를 내놓았는데요. 설정해두면 VSCode나 Cursor의 AI 채팅에서 자연어로 요청하는 것만으로 GitHub의 이슈나 PR을 간편하게 다룰 수 있게 됩니다.

이번 글에서는 GitHub MCP 서버를 설치하고 실제로 활용하는 방법을 살펴볼게요.

GitHub MCP 서버란?

GitHub MCP 서버는 GitHub이 공식으로 제공하는 MCP 서버입니다. AI 도구가 GitHub 플랫폼의 거의 모든 기능에 접근할 수 있게 해줘요. 저장소 탐색이나 이슈 관리는 물론이고 PR 생성과 리뷰, CI/CD 모니터링, 코드 보안 분석까지 됩니다.

이전에도 GitHub REST API를 통해 프로그래밍적으로 GitHub에 접근할 수 있었습니다. 하지만 REST API는 엔드포인트별로 요청을 직접 구성해야 했고 인증 헤더를 매번 붙여야 했죠. GitHub MCP 서버는 이 API를 AI가 바로 쓸 수 있는 도구(Tool) 형태로 감싸줍니다. curl 명령어를 외울 필요 없이 자연어로 요청하면 AI가 알아서 적절한 API를 호출해주는 셈이에요.

GitHub MCP 서버는 모든 GitHub 사용자가 무료로 쓸 수 있어요. 다만 각 도구가 접근하는 GitHub 기능의 권한 요구사항은 그대로 적용됩니다.

서버 배포 방식

GitHub MCP 서버를 실행하는 방법은 크게 두 가지입니다.

하나는 원격 서버 방식으로, GitHub이 https://api.githubcopilot.com/mcp/에서 직접 호스팅합니다. Docker 설치가 필요 없고 OAuth 인증을 사용하며 패치나 업그레이드도 자동으로 적용돼요. 설정이 간단해서 대부분의 경우 이 방식을 추천합니다.

다른 하나는 로컬 서버 방식입니다. Docker 이미지(ghcr.io/github/github-mcp-server)를 받아서 직접 실행하는 건데요. GitHub Personal Access Token(PAT)이 필요하고, 네트워크 제약이 있거나 세밀하게 제어하고 싶을 때 쓰면 좋습니다.

과거에 npm 패키지(@modelcontextprotocol/server-github)를 사용하셨다면 주의하세요. 2025년 4월부터 해당 패키지는 더 이상 지원되지 않으며, github/github-mcp-server로 전환해야 합니다.

Personal Access Token 발급

로컬 서버 방식은 항상 PAT이 필요하고, 원격 서버도 클로드 코드처럼 OAuth를 지원하지 않는 클라이언트에서는 PAT이 필요합니다. VS Code처럼 OAuth를 지원하는 환경이라면 이 섹션은 건너뛰어도 돼요.

GitHub에서 Settings > Developer settings > Personal access tokens로 이동합니다. Fine-grained 토큰과 Classic 토큰 중 선택할 수 있는데, GitHub은 Fine-grained 토큰을 권장합니다. 저장소와 권한을 세밀하게 지정할 수 있어서 보안상 유리하거든요.

Fine-grained 토큰을 생성할 때는 먼저 접근할 저장소를 선택하고, 다음 권한을 부여하면 됩니다.

Contents (Read and write) — 파일 읽기/쓰기, 커밋
Issues (Read and write) — 이슈 생성/조회/수정
Pull requests (Read and write) — PR 생성/리뷰/머지
Metadata (Read-only) — 저장소 기본 정보 (자동 선택됨)
Actions (Read-only) — 워크플로우 모니터링 (필요시)

Classic 토큰(ghp_ 접두사)을 쓸 수도 있습니다. 필요한 주요 스코프는 다음과 같아요.

repo — 저장소, 이슈, PR에 대한 전체 접근
read:org — 조직 멤버십 정보 조회
project — GitHub Projects 관리 (필요시)
notifications — 알림 관리 (필요시)
security_events — 코드 스캐닝, 시크릿 스캐닝 알림 조회 (필요시)

Classic 토큰을 쓰면 GitHub MCP 서버가 스코프를 자동으로 감지해서 권한 없는 도구는 아예 숨겨주는 편의 기능도 있습니다.

토큰을 생성하면 반드시 안전한 곳에 복사해두세요. 페이지를 떠나면 다시 볼 수 없거든요.

PAT의 스코프는 실제로 필요한 것만 부여하는 게 좋습니다. 모든 스코프를 다 켜놓으면 AI가 의도치 않게 민감한 작업을 할 수도 있거든요. GitHub MCP 서버는 보안을 강화할 수 있는 추가 옵션도 제공합니다.

읽기 전용 모드 — 쓰기 도구를 아예 비활성화합니다. 원격 서버에서는 "X-MCP-Readonly": "true" 헤더를 추가하면 돼요.
잠금 모드 — 공개 저장소에서 push 권한이 없는 외부 기여자의 이슈, 코멘트, PR을 AI에게 보여주지 않습니다. 외부인이 이슈나 코멘트에 악의적인 프롬프트를 심어놓는 인젝션 공격을 차단할 수 있어요. "X-MCP-Lockdown": "true" 헤더로 켭니다.
콘텐츠 살균 — 유니코드 보이지 않는 문자나 위험한 HTML 태그, 코드 블록 안에 숨겨진 텍스트를 자동으로 걸러냅니다. 이 기능은 기본으로 켜져 있어요.

아래 도구별 설정 예시에서 이 보안 헤더를 포함한 권장 설정을 보여드릴게요.

Claude Code에서 설정하기

클로드 코드에서는 원격 서버와 로컬 서버 모두 쓸 수 있습니다. claude mcp add 명령어 한 줄이면 끝이에요.

원격 서버 방식은 이렇게 해요. 읽기 전용 모드와 잠금 모드 헤더를 함께 넣어두면 안전합니다.

claude mcp add-json github '{
  "type": "http",
  "url": "https://api.githubcopilot.com/mcp/",
  "headers": {
    "Authorization": "Bearer <PAT>",
    "X-MCP-Readonly": "true",
    "X-MCP-Lockdown": "true"
  }
}'

쓰기 작업(이슈 생성, PR 머지 등)이 필요하다면 X-MCP-Readonly 헤더를 빼면 됩니다.

로컬 Docker 서버를 쓰고 싶다면 이렇게요.

claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=<PAT> \
  -- docker run -i --rm \
  -e GITHUB_PERSONAL_ACCESS_TOKEN \
  ghcr.io/github/github-mcp-server

설정 범위도 지정할 수 있습니다.

--scope local (기본값) — 현재 프로젝트에서 나만 사용
--scope project — .mcp.json에 저장되어 팀 전체가 사용
--scope user — 모든 프로젝트에서 사용

잘 설정되었는지 확인해볼게요.

# 등록된 MCP 서버 목록 확인
claude mcp list

# github 서버 상세 정보
claude mcp get github

클로드 코드 안에서 /mcp 명령어를 입력하면 현재 연결된 MCP 서버의 상태를 확인할 수 있습니다.

클로드 코드의 플러그인 시스템을 통해서도 GitHub MCP 서버를 설치할 수 있습니다. /plugin install github@claude-plugins-official 명령어로 설치하면 PAT 설정까지 한 번에 처리됩니다.

VS Code에서 설정하기

VS Code에서는 프로젝트 루트의 .vscode/mcp.json 파일에 다음을 추가하면 됩니다. VS Code가 OAuth 인증을 처리해주므로 Authorization 헤더는 필요 없고, 보안 헤더만 넣으면 돼요.

.vscode/mcp.json

{
  "servers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "X-MCP-Readonly": "true",
        "X-MCP-Lockdown": "true"
      }
    }
  }
}

Git에 커밋해두면 팀원도 같은 설정을 쓸 수 있어서 좋습니다.

Cursor에서 설정하기

Cursor도 MCP를 지원하므로 비슷한 방식으로 설정할 수 있어요. Cursor Settings > MCP에서 추가하거나, 프로젝트 루트의 .cursor/mcp.json 파일을 직접 만들면 됩니다.

.cursor/mcp.json

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${env:GITHUB_PERSONAL_ACCESS_TOKEN}",
        "X-MCP-Readonly": "true",
        "X-MCP-Lockdown": "true"
      }
    }
  }
}

${env:GITHUB_PERSONAL_ACCESS_TOKEN} 구문은 시스템 환경 변수를 참조합니다. 설정 파일에 토큰을 직접 넣지 않아도 되니까 Git에 커밋해도 안전해요.

글로벌 설정으로 쓰고 싶다면 ~/.cursor/mcp.json에 같은 내용을 넣으면 모든 프로젝트에서 사용할 수 있습니다.

제공되는 도구 살펴보기

GitHub MCP 서버의 도구는 툴셋(toolset)이라는 그룹 단위로 묶여 있습니다. 기본으로 켜져 있는 것과 필요할 때 추가로 켜는 것으로 나뉘어요.

기본 툴셋으로는 repos(저장소 탐색과 파일 읽기, 브랜치 관리), issues(이슈 생성/조회/수정), pull_requests(PR 생성/리뷰/머지), users(사용자 검색), context(현재 사용자 정보)가 있습니다.

추가 툴셋으로는 actions(GitHub Actions 워크플로우 모니터링), code_security(코드 스캐닝과 Dependabot 알림), secret_protection(시크릿 스캐닝), notifications(알림 관리), projects(GitHub Projects) 등이 있고요.

추가 툴셋을 켜려면 로컬 서버는 환경 변수나 CLI 플래그를, 원격 서버는 HTTP 헤더를 씁니다.

# 로컬 서버: 환경 변수로 툴셋 지정
GITHUB_TOOLSETS="repos,issues,pull_requests,actions,code_security"

# 원격 서버: HTTP 헤더로 지정 (claude mcp 설정 시)
"headers": {
  "Authorization": "Bearer <PAT>",
  "X-MCP-Toolsets": "default,code_security,actions"
}

도구가 너무 많으면 AI의 컨텍스트 윈도우를 불필요하게 차지합니다. 원격 서버에서는 X-MCP-Tools 헤더로 필요한 도구만 골라서 로드할 수도 있어요. get_file_contents, pull_request_read, issue_write 세 개만 로드해도 컨텍스트 사용량을 60~90% 줄일 수 있거든요.

실전 활용 예시

설정이 끝났으니 실제로 어떻게 쓸 수 있는지 살펴볼게요.

가장 흔하게 쓰게 되는 건 이슈 관리입니다. “이 저장소의 미해결 이슈를 보여줘”라고 하면 search_issues 도구로 목록을 가져오고, “로그인 페이지에 CSRF 토큰 검증이 빠져 있다는 이슈를 만들어줘”라고 하면 create_issue로 바로 생성해줍니다.

PR 리뷰도 꽤 쓸 만해요. “PR #42의 변경 사항을 요약해줘”라고 하면 diff를 읽고 정리해주고, 리뷰 코멘트까지 작성할 수 있거든요.

개인적으로 가장 유용하다고 느낀 건 코드 검색입니다. “우리 조직에서 deprecated된 fetchLegacyData 함수를 쓰고 있는 곳을 모두 찾아줘”라고 하면 여러 저장소에 걸쳐 검색해줍니다. 마이그레이션 작업 범위 파악할 때 이만한 게 없죠.

actions 툴셋을 켜두면 CI/CD 디버깅도 됩니다. “어젯밤 release.yml 워크플로우가 왜 실패했어?”라고 물으면 로그를 분석해서 원인을 알려줘요. code_security 툴셋으로는 Dependabot 알림을 조회하고 이슈로 만드는 것까지 한 번에 처리할 수 있습니다.

주요 도구 정리

자주 쓰게 될 도구를 정리해두면 작업할 때 한결 편합니다.

저장소

get_file_contents — 파일이나 디렉토리 내용 읽기
search_code — 코드 검색
search_repositories — 저장소 찾기
create_or_update_file — 파일 생성/수정
push_files — 여러 파일 한 번에 커밋

이슈

create_issue — 이슈 생성
issue_read — 이슈 조회
issue_write — 이슈 수정
add_issue_comment — 댓글 달기
search_issues — 이슈 검색

create_pull_request — PR 생성
pull_request_read — PR 조회
pull_request_review_write — 리뷰 작성
merge_pull_request — PR 머지
search_pull_requests — PR 검색

참고로 2025년 하반기부터 GitHub은 비슷한 기능의 도구를 하나로 통합하고 있습니다. 예를 들어 pull_request_read 하나가 예전의 get_pull_request, get_pull_request_diff, get_pull_request_files 등 6개 이상의 도구를 대체하는 식이에요. method 파라미터로 세부 동작을 구분합니다.

GitHub Enterprise 환경

GitHub Enterprise Server나 Data Residency를 쓰는 환경에서도 GitHub MCP 서버를 쓸 수 있습니다. 로컬 서버 설정에서 GITHUB_HOST 환경 변수만 지정하면 돼요.

{
  "env": {
    "GITHUB_PERSONAL_ACCESS_TOKEN": "<PAT>",
    "GITHUB_HOST": "https://github.your-company.com"
  }
}

원격 서버 엔드포인트도 Enterprise 환경에 맞게 바꿔야 할 수 있으니 조직의 GitHub 관리자에게 확인해보세요.

문제 해결

설정 후 도구가 동작하지 않을 때 확인해볼 것을 정리해봤어요.

먼저 원격 서버 연결을 확인해볼게요.

curl -I https://api.githubcopilot.com/mcp/_ping

200 OK가 돌아오면 서버 자체는 정상이에요. 그래도 안 되면 PAT의 스코프가 맞는지 확인해보세요.

curl -sI -H "Authorization: Bearer $GITHUB_PERSONAL_ACCESS_TOKEN" \
  https://api.github.com/user | grep -i x-oauth-scopes

현재 토큰에 어떤 스코프가 부여되어 있는지 볼 수 있습니다. 원하는 도구가 안 보인다면 관련 스코프가 빠져있을 가능성이 높아요.

Docker 관련 에러가 나면 Docker Desktop이 실행 중인지 확인하고 이미지를 다시 받아보세요.

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

클로드 코드에서는 /mcp 명령어로 서버 상태를 확인하고 claude --debug 모드로 자세한 로그를 볼 수 있습니다.

마치며

GitHub MCP 서버를 설정해두면 이슈 생성이나 PR 리뷰, 코드 검색, CI 디버깅 같은 반복 작업을 자연어 한 마디로 처리할 수 있습니다. GitHub REST API를 직접 호출하거나 gh CLI를 쓰던 것에 비하면 진입 장벽이 많이 낮아졌죠.

처음 시작한다면 원격 서버 방식으로 간단히 연결해보고 이슈 조회나 PR 요약 같은 읽기 작업부터 시도해보세요. 익숙해지면 이슈 자동 생성이나 코드 리뷰 같은 쓰기 작업으로 범위를 넓혀가면 됩니다.

MCP의 기본 개념이 궁금하거나 MCP 서버를 직접 찾아보고 싶다면 MCP Registry 활용 가이드도 참고해보세요. 공식 설치 가이드에서 더 자세한 설정 옵션을 확인할 수 있어요.

GitHub 외에도 다양한 MCP 서버를 클로드 코드에 연결하는 방법은 클로드 코드에서 MCP 서버 연동하기에서 다루고 있습니다.

This work is licensed under CC BY 4.0

GitHub MCP 서버란?

서버 배포 방식

Personal Access Token 발급

Claude Code에서 설정하기

VS Code에서 설정하기

Cursor에서 설정하기

제공되는 도구 살펴보기

실전 활용 예시

주요 도구 정리

GitHub Enterprise 환경

문제 해결

마치며

관련 포스트

Playwright MCP로 AI 에이전트에게 브라우저 자동화 맡기기

클로드 코드에서 MCP 서버 연동하기

클로드 코드 자동 메모리: AI가 스스로 배우고 기억하는 법

SponsorKit으로 오픈소스 후원자에게 감사하기

뉴스레터 구독