개발자를 위한 MCP 추천(2) - GitHub MCP 설치 및 사용방법 : 자연어로 GitHub를 조작하는 법, 개발 워크플로우 자동화하기

2026년 3월 · 개발자를 위한 MCP 추천 시리즈

"MCP가 죽었다"말도 나오는데, 그래도 현시점 쓸만한 MCP 10개

2025년에 썼던 개발자용 MCP 시리즈들이, 이제 상당 부분 구버전이 됐다.
생태계가 빠르게 변했고, 새로 등장한 도구들도 많다.
2026년 3월, 다시 한번 실제로 써보고 쓸 만한 것들만 골라 정리해려고 한다.

이 시리즈를 다시 쓰는 이유

지난 2월 말, 필자가 "MCP는 죽었다, CLI 만세 — Eric Holmes의 도발적 주장"이라는 글을 정리한 적이 있다. Eric Holmes가 주장한 핵심은 간단하다. LLM은 이미 CLI에 능숙하다. 그렇다면 MCP라는 별도의 추상 계층이 굳이 필요한가?

실제로 Claude Code 환경에서 MCP 대신 CLI로 해결되는 경우가 꽤 많다. 디버깅도 쉽고, 별도 프로세스 관리도 없고, 기존 인증도 그대로 쓸 수 있다. 그 글에서 공감하신 분들이 많았다.
그럼에도 불구하고, MCP만이 줄 수 있는 가치가 분명히 존재한다.

 

안녕하세요! 갓대희 입니다.

오늘은 개발자를 위한 MCP 시리즈 중에서 "GitHub MCP"에 대해 알아보려고 한다.

이슈 생성, PR 작성, 코드 검색, 리포지토리 관리 — 이 모든 걸 AI와 대화하면서 처리할 수 있다면 어떨까? GitHub가 직접 만든 공식 MCP 서버를 사용하면 가능하다. Claude Code에서 자연어로 GitHub 작업을 자동화하는 방법을 정리해봤다.

 

GitHub MCP : AI가 GitHub를 직접 조작하게 해준다
GitHub가 공식으로 만든 MCP 서버다. Claude Code에 연결하면 이슈 생성, PR 작성, 코드 검색, 파일 수정, 브랜치 관리까지 자연어로 처리할 수 있다. 반복적인 GitHub 작업을 AI에게 위임해서 개발 워크플로를 자동화할 수 있다.

목차

1. GitHub MCP란?
2. GitHub Personal Access Token 발급
3. 설치 방법
4. 주요 Tools 전체 목록
5. 활용 시나리오 — PR 자동화
6. 활용 시나리오 — 이슈 관리 자동화
7. GitHub CLI (gh) vs GitHub MCP 비교
8. 주의사항 및 트러블슈팅
9. 결론

1. GitHub MCP란?

GitHub MCP는 GitHub가 공식으로 개발한 MCP(Model Context Protocol) 서버다. AI 에이전트가 GitHub API를 통해 리포지토리, 이슈, PR, 코드 등을 직접 읽고 쓸 수 있게 해준다.

GitHub: https://github.com/github/github-mcp-server

두 가지 서버 버전

• 로컬 서버 — Docker 또는 사전 빌드된 바이너리로 직접 실행. GITHUB_PERSONAL_ACCESS_TOKEN 필요.
• 원격 서버 — https://api.githubcopilot.com/mcp/로 접속. OAuth 인증 지원. VS Code 1.101+ 필요.

이 글에서는 Claude Code에서 가장 많이 쓰는 로컬 서버(Docker 방식)를 기준으로 설명한다.

 

2. GitHub Personal Access Token 발급

GitHub MCP 로컬 서버를 사용하려면 GitHub Personal Access Token(PAT)이 필요하다. Fine-grained token 사용을 권장한다.

 

발급 단계

1. GitHub 로그인 후 Settings 이동
2. 좌측 메뉴 맨 아래 Developer settings 클릭
3. Personal access tokens → Fine-grained tokens 선택
4. Generate new token 클릭
5. Token name 입력, Expiration 설정 (90일 권장)
6. Repository access: All repositories 또는 특정 리포지토리 선택
7. Permissions 설정 (아래 표 참고)
8. Generate token 클릭 후 토큰 복사 — 이 화면 벗어나면 다시 볼 수 없음

 

권장 Permissions

용도에 맞게 최소 권한만 부여하는 것이 보안상 좋다.

Permission	Access Level	필요한 기능
Contents	Read & Write	파일 읽기/쓰기, 커밋
Issues	Read & Write	이슈 생성/수정/댓글
Pull requests	Read & Write	PR 생성/리뷰/병합
Metadata	Read-only	리포지토리 정보 조회 (필수)
Actions	Read-only	CI/CD 워크플로 조회 (선택)

보안 주의사항

• 토큰은 절대 코드에 하드코딩하지 않는다. 환경 변수로만 관리한다.
• 필요한 최소 권한만 부여한다 (최소 권한 원칙).
• 만료 기간을 설정하고 주기적으로 갱신한다.
• 토큰이 유출되었으면 즉시 GitHub에서 revoke한다.

 

3. 설치 방법

Docker를 사용하는 방식이 가장 안정적이고 권장된다. Docker가 설치되어 있어야 한다.

 

이전에도 사실 얘기했지만, 요즘 mcp는 자연어로 매우 쉽게 설치 가능하다. 다만 설치 방법 과정도 직접 해보는것도 좋다고 생각한다. 그렇기 떄문에 직접 설치하는 방법들도 남겨 두고, 자연어로 설치하는 방법도 남겨 두려고 한다. 

 

ex) github mcp 설치 해줘. 한마디 이후 직접 세팅이 필요한 부분은 안내를 해주거나, 몇가지는 입력 또는 선택을 요청해가며 설치할 것이다.

 

방법 1. Claude Code 대화형 설치 (Docker 방식, 권장)

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

Docker 이미지 최초 실행 시
ghcr.io/github/github-mcp-server 이미지를 자동으로 pull한다. 처음 실행할 때 다운로드 시간이 소요될 수 있다. Docker Desktop이 실행 중인지 확인한다.

 

방법 2. settings.json 직접 수정

Claude Desktop의 경우 ~/Library/Application Support/Claude/claude_desktop_config.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": "ghp_xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

 

방법 3. npx 방식 (구 패키지)

구버전 방식으로, @modelcontextprotocol/server-github 패키지를 사용하는 방법도 있다. 단, 공식 github/github-mcp-server로 이전되었으므로 Docker 방식을 권장한다.

# 구버전 방식 (참고용)
claude mcp add github \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx \
  -- npx -y @modelcontextprotocol/server-github

 

환경 변수 설정 (쉘 설정 파일)

토큰을 설정 파일에 하드코딩하지 않고 환경 변수로 관리하는 방법이 더 안전하다.

# ~/.zshrc 또는 ~/.bashrc에 추가
export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_xxxxxxxxxxxxxxxxxxxx"

# 적용
source ~/.zshrc

 

설치 확인

claude mcp list

github가 목록에 나타나면 정상적으로 설치된 것이다.

 

4. 주요 Tools 전체 목록

GitHub MCP는 다양한 Tool을 제공한다. 기능별로 정리했다. (출처: github/github-mcp-server 공식 리포지토리 기준, 버전에 따라 변동 가능)

 

리포지토리 관리

Tool 이름	설명
create_repository	새 리포지토리 생성
fork_repository	리포지토리 포크
get_file_contents	파일 또는 디렉토리 내용 조회
create_or_update_file	파일 생성 또는 수정 후 커밋
delete_file	파일 삭제
push_files	여러 파일을 한 번에 커밋&푸시
list_branches	브랜치 목록 조회
create_branch	새 브랜치 생성
list_commits	커밋 히스토리 조회
get_commit	특정 커밋 상세 조회

 

이슈 관리

Tool 이름	설명
list_issues	이슈 목록 조회 (필터 지원)
issue_read	특정 이슈 상세 조회
issue_write	이슈 생성 및 수정
add_issue_comment	이슈에 댓글 추가
list_issue_types	이슈 타입 목록 조회
get_label	레이블 정보 조회
assign_copilot_to_issue	이슈에 GitHub Copilot 할당

 

Pull Request 관리

Tool 이름	설명
list_pull_requests	PR 목록 조회
pull_request_read	특정 PR 상세 조회
create_pull_request	새 PR 생성
merge_pull_request	PR 병합
pull_request_review_write	PR 리뷰 작성
add_reply_to_pull_request_comment	PR 댓글에 답글 추가
add_comment_to_pending_review	대기 중인 리뷰에 댓글 추가

 

검색

Tool 이름	설명
search_code	GitHub 전체 코드 검색 (GitHub 네이티브 검색 엔진)
search_repositories	리포지토리 검색 (고급 검색 문법 지원)
search_issues	이슈 검색 (GitHub 이슈 검색 문법 사용)
search_pull_requests	PR 검색 (GitHub PR 검색 문법 사용)
search_users	GitHub 사용자 검색

 

릴리즈 / 사용자 / 기타

Tool 이름	설명
get_me	현재 인증된 사용자 정보 조회
list_releases	릴리즈 목록 조회
get_latest_release	최신 릴리즈 조회
get_release_by_tag	특정 태그 릴리즈 조회
list_tags	태그 목록 조회
get_tag	특정 태그 상세 조회
get_teams	조직 팀 목록 조회
get_team_members	팀 멤버 목록 조회

참고: GitHub MCP Server는 지속적으로 업데이트되고 있으며 tool 목록은 버전에 따라 변동될 수 있다. 최신 전체 목록은 공식 README에서 확인한다.

 

5. 활용 시나리오 — PR 자동화

가장 강력한 활용 사례 중 하나다. 코드 작성부터 PR 생성, 리뷰 요청까지 Claude Code와 대화하면서 처리할 수 있다.

 

시나리오 1: 기능 개발 후 PR 생성

단계별 흐름

1. Claude Code에서 기능 코드 작성 및 로컬 커밋
2. GitHub MCP로 새 브랜치 생성
3. 변경된 파일들을 브랜치에 푸시
4. PR 자동 생성 (제목, 본문, 관련 이슈 링크 포함)
5. 리뷰어 지정 요청 (선택)

사용자: user-auth 기능 개발이 완료됐어. my-org/my-repo에서 feat/user-auth 브랜치를 main에서 새로 만들고, 현재 변경된 파일들을 거기에 올린 다음, PR을 만들어줘. PR 제목: feat: 사용자 인증 기능 추가. 관련 이슈: #42

 

Claude: 브랜치 생성, 파일 푸시, PR 생성을 순서대로 진행하겠습니다.

Step 1: create_branch → feat/user-auth (from main) -- 완료

Step 2: push_files → src/auth.ts, src/middleware.ts, tests/auth.test.ts 3개 파일 커밋 -- 완료

Step 3: create_pull_request → PR #93 생성 완료

PR이 생성되었습니다:

PR #93: feat: 사용자 인증 기능 추가
feat/user-auth → main | 3 files changed | Closes #42

Claude Code가 내부적으로 다음 순서로 GitHub MCP Tools를 호출한다:

1. create_branch → feat/user-auth (from main)
2. push_files → 변경 파일들을 feat/user-auth에 커밋
3. create_pull_request →
   {
     title: "feat: 사용자 인증 기능 추가",
     head: "feat/user-auth",
     base: "main",
     body: "## 변경 사항\n...\n\nCloses #42"
   }

 

시나리오 2: 코드 리뷰 자동 작성

사용자: my-org/my-repo의 PR #87 코드 변경사항을 검토하고 잠재적인 버그나 개선점이 있으면 리뷰 댓글로 작성해줘.

 

Claude: PR #87을 분석하겠습니다.

pull_request_read → PR #87: "refactor: 결제 로직 분리" (5 files changed, +142 -89)

get_file_contents → src/payment/processor.ts, src/payment/validator.ts 분석 완료

pull_request_review_write → 리뷰 작성 완료

코드 리뷰를 작성했습니다. 주요 피드백:

• processor.ts:45 — amount에 대한 음수 검증이 빠져 있습니다
• validator.ts:23 — try-catch에서 에러를 삼키고 있어 디버깅이 어려울 수 있습니다
• 전반적으로 관심사 분리가 잘 되었습니다. APPROVE with comments로 작성했습니다.

Claude가 pull_request_read로 변경 파일을 읽고, get_file_contents로 코드를 분석한 뒤, pull_request_review_write로 리뷰를 작성한다. 리뷰 댓글은 실제 GitHub PR 화면에서 볼 수 있다.

 

6. 활용 시나리오 — 이슈 관리 자동화

시나리오 3: 버그 리포트 이슈 자동 생성

사용자: 사용자 로그인 시 500 에러가 발생하는 버그가 있어. my-org/my-repo에 버그 리포트 이슈를 만들어줘. 레이블: bug, priority: high

 

Claude: 버그 리포트 이슈를 생성하겠습니다.

issue_write → Issue #128 생성 완료

이슈가 생성되었습니다:

#128: [Bug] 로그인 시 500 Internal Server Error 발생

bug priority: high

재현 단계, 예상 동작, 실제 동작이 구조화된 형태로 작성됨

Claude가 issue_write를 호출해서 제목, 재현 단계, 예상 동작, 실제 동작이 구조화된 이슈를 자동으로 생성한다.

 

시나리오 4: 미해결 이슈 분석 및 우선순위 정리

사용자: my-org/my-repo의 open 상태 이슈 목록을 가져와서 심각도 순으로 정리해서 보여줘. 각 이슈별로 예상 수정 난이도도 평가해줘.

 

Claude: 이슈 목록을 조회하고 분석하겠습니다.

list_issues → open 이슈 12개 조회 완료

#128	로그인 500 에러	심각도: 높음	난이도: 중
#125	결제 금액 소수점 반올림 오류	심각도: 높음	난이도: 낮
#120	다크모드 전환 시 깜빡임	심각도: 중간	난이도: 낮

... 외 9건

Claude가 list_issues로 이슈 목록을 가져오고, 각 이슈 내용을 분석해서 정리된 형태로 응답한다.

 

시나리오 5: 코드 검색으로 버그 패턴 찾기

사용자: GitHub에서 my-org/my-repo 리포지토리 안에 'console.log'를 코드에서 찾아줘. 프로덕션에 남은 디버그 로그를 확인하고 싶어.

 

Claude: 코드 검색을 실행하겠습니다.

search_code query: "console.log repo:my-org/my-repo" → 7건 발견

프로덕션 코드에서 console.log가 7곳 발견되었습니다:

src/api/users.ts:23   console.log('user data:', userData)

src/api/payment.ts:87   console.log('payment result', result)

src/utils/debug.ts:5   console.log('debug mode enabled')

... 외 4건

Claude가 search_code를 사용해서 GitHub의 네이티브 코드 검색 엔진으로 정확한 결과를 반환한다. 파일 경로와 라인 번호까지 포함되어 바로 수정할 위치를 파악할 수 있다.

 

시나리오 6: 멀티 레포 작업 — 여러 리포지토리 동시 관리

GitHub MCP는 하나의 토큰으로 접근 가능한 모든 리포지토리를 다룰 수 있다. 여러 레포의 상태를 한 번에 파악하거나 일괄 작업이 가능하다.

사용자: my-org/frontend와 my-org/backend 두 레포에서 이번 주 생성된 PR 목록을 한 번에 보여줘.

 

Claude: 두 리포지토리의 최근 PR을 조회하겠습니다.

list_pull_requests("my-org/frontend") → 3건

list_pull_requests("my-org/backend") → 2건

이번 주 PR 현황입니다:

my-org/frontend (3건)

#201 feat: 검색 필터 UI 개선 — merged

#202 fix: 모바일 레이아웃 깨짐 — review requested

#203 chore: deps 업데이트 — open

my-org/backend (2건)

#89 feat: 검색 API 엔드포인트 추가 — merged

#90 fix: N+1 쿼리 최적화 — review requested

멀티 레포 작업의 장점
프론트엔드/백엔드가 분리된 프로젝트에서 "검색 기능 관련 PR 전체 현황을 보여줘"처럼 기능 단위로 여러 레포를 한 번에 파악할 수 있다. gh CLI로는 레포별로 명령어를 따로 실행해야 하지만, GitHub MCP에서는 자연어 하나로 처리된다.

 

7. GitHub CLI (gh) vs GitHub MCP 비교

GitHub MCP를 쓰면 기존에 사용하던 gh CLI가 필요 없을까? 두 도구의 차이를 알면 각각 언제 쓸지 판단하기 쉽다.

항목	GitHub CLI (gh)	GitHub MCP
사용 방식	터미널 명령어 직접 입력	AI와 자연어 대화
학습 곡선	명령어/플래그 암기 필요	자연어로 요청
자동화 스크립트	셸 스크립트로 쉽게 자동화	AI 에이전트 내에서 자동화
컨텍스트 활용	없음 (명시적 파라미터만)	대화 컨텍스트 활용 가능
복합 작업	여러 명령 수동 조합 필요	AI가 여러 Tool을 자동 조합
정밀 제어	플래그로 세밀한 제어 가능	자연어 이해에 의존
CI/CD 파이프라인	적합	부적합 (AI 에이전트 환경 필요)
코드와 연동	별도 작업 필요	코드 작성 → GitHub 작업 연속으로 처리

어떤 걸 써야 할까?
둘을 같이 쓰면 된다. Claude Code 내에서 코드를 작성하고 GitHub 작업을 함께 처리할 땐 GitHub MCP, CI/CD 파이프라인이나 셸 스크립트 자동화는 gh CLI가 더 적합하다. 두 도구는 서로 대체재가 아니라 보완재다.

 

8. 주의사항 및 트러블슈팅

문제 1: 401 Unauthorized — 토큰 인증 실패
GITHUB_PERSONAL_ACCESS_TOKEN이 잘못 설정되었거나 만료된 경우 발생한다.
해결:

• 토큰이 올바르게 설정되었는지 확인: echo $GITHUB_PERSONAL_ACCESS_TOKEN
• 토큰 만료 여부 확인 후 GitHub에서 새 토큰 발급
• 필요한 권한(Permissions)이 포함되어 있는지 확인

문제 2: Docker가 실행되지 않음
Docker Desktop이 꺼져 있으면 MCP 서버가 시작되지 않는다.
해결: Docker Desktop을 실행하고 Claude Code를 재시작한다. docker ps로 Docker 상태를 확인할 수 있다.

문제 3: 403 Forbidden — 권한 부족
토큰에 필요한 권한이 없을 때 발생한다.
해결: GitHub에서 토큰 설정으로 가서 필요한 Permissions를 추가한다. 특히 조직 리포지토리의 경우 Organization access도 승인해야 한다.

문제 4: rate limit 초과
GitHub API는 인증된 요청 기준 시간당 5,000회 요청 제한이 있다. 대량의 검색이나 조회 시 초과할 수 있다.
해결: 잠시 기다리거나, 불필요한 반복 요청을 줄인다.

주의: 쓰기 작업은 되돌리기 어렵다
create_or_update_file, merge_pull_request, delete_file 같은 쓰기 작업은 실제 GitHub에 반영된다. AI에게 쓰기 작업을 위임할 때는 프롬프트를 정확하게 작성하고, 실행 전 확인 단계를 두는 것이 좋다.

 

9. 결론

GitHub MCP는 AI 코딩 워크플로에서 GitHub 작업을 자연어로 처리할 수 있게 해주는 강력한 도구다. 코드 작성 → 브랜치 생성 → 파일 푸시 → PR 생성 → 리뷰까지, Claude Code 대화창을 벗어나지 않고 처리할 수 있다.

특히 반복적인 이슈 생성, PR 작성, 코드 검색 같은 작업을 AI에게 위임하면 개발 흐름을 끊지 않고 생산성을 높일 수 있다.

GitHub MCP 핵심 요약

• 공식 리포: github/github-mcp-server
• 설치: claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=... -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
• 필요: Docker, GitHub Personal Access Token (Fine-grained 권장)
• 주요 Tools: create_pull_request, issue_write, search_code, get_file_contents 등 20개 이상
• 토큰은 환경 변수로 관리, 최소 권한 원칙 적용

 

참고: GitHub - github/github-mcp-server / GitHub Docs - Using the GitHub MCP Server / GitHub Blog - Practical Guide