Claude에 GitHub 전체를 연결하다 — GitHub MCP 플러그인 실전 가이드

코드를 짜다가 PR을 확인해야 할 때마다 브라우저로 넘어가는 흐름이 끊기는 느낌이 있다. GitHub 탭을 열고, 필터를 걸고, 코멘트를 달고, 다시 에디터로 돌아오는 과정이다. GitHub MCP 플러그인을 설치하면 이 흐름이 사라진다. Claude Code 대화창 안에서 "내가 리뷰어로 지정된 PR 목록 보여줘"라고 하면 즉시 목록이 나오고, "이 PR에 LGTM 코멘트 달아줘"라고 하면 GitHub에 바로 반영된다.

이 플러그인이 흥미로운 이유는 HTTP 방식의 MCP 서버라는 점이다. 앞서 설명한 서브에이전트의 3가지 핵심 구성요소 중 플러그인이 제공하는 것은 도구 목록(②)만이다. 시스템 프롬프트(①)와 트리거(③)는 사용자가 별도로 정의한다. GitHub API와 통신하는 MCP 서버가 GitHub Copilot 인프라에서 운영되고, 그 서버를 Claude Code가 HTTP로 호출하는 구조다. 로컬에 별도 프로세스가 뜨지 않는다.

핵심은 아키텍처 그림 가운데 있는 "GitHub MCP 서버"다. 이 서버는 로컬 컴퓨터에 뜨는 프로세스가 아니라, api.githubcopilot.com/mcp/라는 원격 서버다. Claude Code가 HTTP로 이 서버를 호출하고, 서버가 GitHub.com API를 대신 호출해 결과를 돌려준다. npx로 로컬 프로세스를 띄우는 Playwright나 context7과 다른 방식이고, 덕분에 Node.js 설치 없이도 동작한다.

3가지 구성요소와의 관계

GitHub MCP 플러그인은 서브에이전트의 3가지 핵심 구성요소 중 ② 도구 목록만 제공한다. PR을 읽고 코멘트를 다는 도구들이 Claude Code에 추가되는 것이다. ① 시스템 프롬프트("PR 리뷰어로서 보안을 중점적으로 확인한다")와 ③ 트리거("리뷰해줘")는 사용자가 별도로 SKILL.md를 만들어 정의해야 한다.

직접 SKILL.md를 만들어 붙여 보자. GitHub MCP가 제공하는 도구를 활용하는 PR 리뷰어 에이전트다.

# ~/.claude/skills/pr-reviewer/SKILL.md
---
name: pr-reviewer
description: GitHub PR을 자동으로 리뷰하는 에이전트
triggers:
  - PR 리뷰
  - pull request 확인
  - PR 머지해도 돼
allowed-tools:
  - mcp__plugin_github_github__list_pull_requests
  - mcp__plugin_github_github__pull_request_read
  - mcp__plugin_github_github__pull_request_review_write
  - mcp__plugin_github_github__add_issue_comment
  - mcp__plugin_github_github__merge_pull_request
  - mcp__plugin_github_github__request_copilot_review
---

당신은 시니어 소프트웨어 엔지니어로, 팀의 PR 리뷰를 담당합니다.

## 리뷰 절차

1. pull_request_read로 변경 내용을 파악한다.
2. 보안 → 로직 → 스타일 순으로 이슈를 분류한다.
3. pull_request_review_write로 구체적 코멘트를 단다.
4. 머지 가능 여부를 판단해 결론을 내린다.

## 리뷰 기준

- SQL Injection, XSS 등 보안 패턴을 우선 확인한다.
- 테스트가 없는 변경에는 반드시 지적한다.
- 좋은 코드도 반드시 언급해 균형을 유지한다.

설치 방법

플러그인 설치는 한 줄이다. 그 다음 GitHub Personal Access Token(개인 계정 인증 토큰)을 환경변수로 설정해야 한다. PAT는 GitHub → Settings → Developer settings → Personal access tokens에서 생성한다. 필요한 권한은 repo, read:org, read:user다.

# 1단: 플러그인 설치
/plugin install github@claude-plugins-official

# 2단: GitHub PAT 환경변수 설정 (~/.bashrc 또는 ~/.zshrc에 추가)
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# 3단: 위에서 만든 PR 리뷰어 스킬 설치
mkdir -p ~/.claude/skills/pr-reviewer
# (위 SKILL.md 내용을 저장)

# 이제 대화창에서
# 사용자: "my-org/my-repo PR 리뷰해줘"
# → pr-reviewer 스킬이 호출되고 GitHub MCP 도구로 실제 PR을 분석한다

설치 후 파일 구조

설치가 완료되면 Claude Code의 플러그인 캐시 디렉토리에 파일이 생긴다. GitHub MCP 플러그인은 구조가 단순하다 — 파일이 단 두 개다.

~/.claude/plugins/cache/claude-plugins-official/github/unknown/
  .claude-plugin/
    plugin.json     ← 플러그인 메타데이터 (이름·설명·작성자)
  .mcp.json         ← MCP 서버 접속 정보 (핵심 파일)

파일이 두 개뿐이라는 것 자체가 이 플러그인의 특성을 보여준다. 로컬에 설치되는 코드가 없고, 접속 정보만 기록한다. 핵심은 .mcp.json이다.

// .mcp.json — 실제 파일 전체
{
  "github": {
    "type": "http",                               // HTTP 방식 (로컬 프로세스 없음)
    "url": "https://api.githubcopilot.com/mcp/",  // GitHub 운영 원격 서버
    "headers": {
      "Authorization": "Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}"
                                                  // 환경변수에서 PAT를 런타임에 주입
    }
  }
}

이 파일에서 주목할 것이 세 가지 있다. 첫째, "type": "http"다. Playwright나 sequential-thinking의 "command": "npx"와 다르게 HTTP 연결 타입이다 — 원격 서버에 접속하는 방식이라는 뜻이다. 둘째, URL이 githubcopilot.com이다. Anthropic이 아닌 GitHub가 직접 운영하는 서버다. 셋째, ${GITHUB_PERSONAL_ACCESS_TOKEN}은 런타임에 환경변수 값을 읽어서 Bearer 토큰으로 사용한다. 이 환경변수가 설정되지 않으면 모든 도구 호출이 401 인증 오류로 실패한다.

plugin.json은 메타데이터만 담는다.

// .claude-plugin/plugin.json
{
  "name": "github",
  "description": "Official GitHub MCP server for repository management. Create issues,
    manage pull requests, review code, search repositories, and interact with GitHub's
    full API directly from Claude Code.",
  "author": { "name": "GitHub" }
}

시스템 프롬프트(①)와 트리거(③)가 이 파일들 어디에도 없다는 점을 확인할 수 있다. 이 플러그인은 도구 목록(②)만 제공하고, 나머지는 사용자가 SKILL.md로 채워야 한다.

어떤 효과가 있나

GitHub MCP 플러그인의 효과는 세 가지로 정리된다. 첫째, 컨텍스트 전환이 사라진다. 코드를 짜다가 PR을 확인할 때 브라우저로 넘어갈 필요가 없다. Claude Code 대화창 안에서 모든 GitHub 작업이 완결된다.

둘째, 복합 작업을 자연어 한 마디로 실행한다. "내가 reviewer인 PR 중 7일 이상 지난 것 목록 보여주고 각각 머지 가능 여부 판단해줘"는 수십 번의 클릭이 필요한 작업이지만, Claude에게 한 문장으로 요청하면 된다. Claude가 search_pull_requests, pull_request_read, list_commits를 차례로 호출해 판단 결과를 낸다.

셋째, 보안 스캔과 코드 리뷰를 함께 자동화한다. PR이 열릴 때마다 search_code로 위험 패턴을 찾고 run_secret_scanning으로 비밀 토큰 노출을 확인하는 루틴을 만들어 두면, 별도 CI 도구 없이 Claude가 매번 자동으로 실행한다.

주의할 점은 하나다. merge_pull_request, pull_request_review_write 같은 쓰기 작업은 실행 전 Claude Code가 사용자에게 확인을 요청한다. 직접 GitHub에 영향을 주는 작업이므로 Claude Code의 기본 동작이 이를 사용자 확인 대상으로 분류하기 때문이다.

---

이 글은 생성형 AI의 도움을 받아 작성되었습니다. 원본 자료를 기반으로 AI가 초안을 생성하고, 작성자가 검토·편집하였습니다.