GitHub MCP와 Claude Code 연결하기: 단계별 가이드 (2026)

Claude Code의 GitHub MCP란 무엇인가요(무엇을 할 수 있나요)?

GitHub MCP 서버는 Claude Code가 자연어로 GitHub를 직접 읽고 조작할 수 있게 해 주는 다리 역할이에요 - 터미널을 떠날 필요도, 수동으로 복사·붙여넣기를 할 필요도 없어요. MCP(Model Context Protocol)는 AI를 외부 도구와 연결하는 개방형 표준이에요. 이 개념이 처음이라면 MCP란 무엇이고 어떻게 동작하는지부터 읽어 보세요.

연결되면 저장소와 open 상태의 issue 목록 보기, 새 issue 만들기, pull request 열기, PR의 코드 리뷰, 설명으로 코드 검색, 저장소 안의 파일 읽기 같은 작업을 Claude에게 요청할 수 있어요. 브라우저를 열어 GitHub를 클릭해 가며 다니는 대신, 한 문장만 입력하면 Claude가 대신 GitHub API를 호출해요. 이것이 개별 gh 명령을 하나씩 실행하는 것과 다른 점이에요: Claude는 세션 전체의 맥락을 이해하고 알맞은 도구를 스스로 골라요.

실제 예를 들어 볼게요. 버그를 고치는 도중에 "이 타임아웃 오류와 관련된 issue를 찾아서 댓글을 요약해 줘"라고 말하면, Claude가 GitHub에 질의하고 issue를 읽어 터미널에서 바로 답해 줘요 - 창을 전환할 필요가 없어요. 수정한 뒤에는 이어서 "현재 브랜치에서 PR을 열고 그 issue를 참조해 줘"라고 요청할 수 있어요. 이 일련의 작업이 모두 하나의 대화 안에서 이뤄지며, 작업 중인 코드의 맥락이 그대로 유지돼요. 그래서 많은 개발자가 GitHub MCP를 매번 켰다 껐다 하지 않고 기본 도구로 연결해 둬요.

시작하기 전에(체크리스트)

서버를 추가하기 전에 다음을 빠르게 확인해 두세요:

• Claude Code가 설치되어 있고 터미널에서 실행되는지 - 아직이라면 Claude Code 설치 방법을 참고하세요.
• Claude에게 작업시키려는 저장소에 접근할 수 있는 GitHub 계정.
• 연결 방식 선택: 원격 HTTP(추천 - 빠르고 설치할 것이 없어요) 또는 Docker(서버를 내 컴퓨터에서 로컬로 돌리고 싶은 경우). 대부분은 원격 HTTP로 충분해요.
• Docker를 선택한다면 Docker Desktop을 설치하고, 서버를 추가하기 전에 미리 실행해 두세요.

원격 HTTP 방식이라면 이 가이드 전체가 약 5~10분이면 끝나요.

2026년 가장 빠른 방법: 공식 플러그인 마켓플레이스로 설치하기

2026년 현재, Claude Code에는 공식 플러그인 마켓플레이스가 기본으로 내장되어 있어요. GitHub MCP를 가장 빠르게 실행하려면 세션 안에서 다음을 입력하세요:

/plugin install github@claude-plugins-official

claude-plugins-official 마켓플레이스는 Claude Code를 대화형으로 처음 실행할 때 자동으로 등록돼요 - 만약 없다면 /plugin marketplace add anthropics/claude-plugins-official로 직접 추가하세요. 이 플러그인에는 사전 구성된 GitHub MCP 서버가 포함되어 있고, 아래 2단계의 -s 플래그에 대응하는 스코프(User/Project/Local)도 그대로 고를 수 있어요. 연결되었는지는 /mcp 또는 /plugin list --enabled로 확인하세요.

⚠️ 아직 확인되지 않음: 플러그인으로 설치할 때에도 PAT 붙여넣기를 요구하는지, 아니면 OAuth/디바이스 플로 로그인이 자동으로 시작되는지는 공식 문서에 명시되어 있지 않아요. 직접 검증하는 대로 이 섹션을 업데이트할게요.

트레이드오프: 더 빠르지만, 아래 4단계 수동 방법보다 스코프·권한 제어가 덜 세밀해요 - 팀이나 프로덕션 환경에서는 필요한 권한을 정확히 고를 수 있는 수동 방법이 여전히 더 안전한 기본 선택이에요.

GitHub 외의 다른 플러그인이나 MCP 서버도 보고 싶으신가요? 2026년 최고의 Claude Code 플러그인 & MCP (기사가 게시되면 링크가 활성화돼요)를 확인해 보세요.

1단계 - GitHub Personal Access Token(PAT) 만들기

GitHub MCP는 여러분을 대신해 API를 호출하기 위해 토큰이 필요해요. GitHub에는 두 종류의 토큰이 있어요: classic(스코프 기반의 넓은 권한)과 fine-grained(저장소별 권한). 필요한 저장소와 권한만 정확히 제한할 수 있어 토큰이 유출되더라도 피해를 최소화할 수 있으니, fine-grained 토큰을 사용하세요:

1. GitHub에서 아바타 -> Settings로 이동해요.
2. 왼쪽 메뉴 맨 아래로 스크롤해 Developer settings를 선택해요.
3. Personal access tokens -> Fine-grained tokens -> Generate new token을 선택해요.
4. 이름(예: claude-code-mcp)을 지정하고 적당한 만료 기간(30~90일)을 설정해요.
5. Repository access에서 Only select repositories를 선택하고, Claude가 다루길 원하는 저장소만 체크해요.
6. Permissions -> Repository permissions에서 필요한 최소한만 부여해요: Contents(파일 읽기/쓰기), Issues, Pull requests. 조직에서 작업한다면 read:org를 추가해요.
7. Generate token을 클릭하고 토큰을 바로 복사해요.

보안 경고: GitHub는 토큰을 단 한 번만 보여줘요. 복사해서 안전한 곳(비밀번호 관리자)에 보관하세요. 토큰을 저장소에 커밋하지 마세요. 또한 git으로 추적되는 어떤 파일에도 붙여넣지 마세요. Claude가 스스로 콘텐츠를 만들거나 편집하길 정말 원할 때에만 쓰기 권한을 부여하세요.

2단계 - GitHub MCP 서버 추가하기(추천: 원격 HTTP)

이것이 가장 빠른 방법이고 Docker도 필요 없어요. 터미널을 열고 YOUR_PAT를 방금 만든 토큰으로 바꾼 다음 실행하세요:

claude mcp add --transport http github https://api.githubcopilot.com/mcp/ -H "Authorization: Bearer YOUR_PAT"

JSON 형식 설정이 더 편하다면(복사해서 바로 쓸 수 있게 준비해 두고 싶을 때 유용해요) 다음 대안을 사용하세요:

claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_PAT"}}'

-s 플래그로 설정 스코프를 선택하세요:

• -s local(기본값): 이 컴퓨터의 현재 디렉터리에만 적용돼요.
• -s user: 내 모든 프로젝트에서 공유돼요 - GitHub MCP를 항상 쓸 수 있게 하면서 토큰을 어떤 저장소에도 두지 않고 싶을 때 유용해요.
• -s project: .mcp.json에 저장되어 git을 통해 팀 전체와 공유돼요. 팀에는 편리하지만 주의하세요: 실제 토큰이 이 파일에 들어가면 절대 안 돼요.

예를 들어 모든 프로젝트에서 공유하려면 위의 claude mcp add 명령 끝에 -s user를 추가하세요. claude mcp add의 전체 문법은 Claude Code MCP 공식 문서(2026년 업데이트)에 있어요.

OAuth에 대한 참고: 2026년 8월 기준으로 Claude Code의 원격 GitHub MCP에서는 OAuth 플로가 아직 완전히 지원되지 않으니, 위처럼 PAT를 쓰는 것이 가장 확실한 방법이에요.

3단계(대안) - Docker로 GitHub MCP 실행하기(로컬)

서버를 전적으로 내 컴퓨터에서 돌리고 싶다면(예를 들어 완전한 제어를 원하거나 격리된 환경에서 실행하고 싶다면) 공식 이미지 ghcr.io/github/github-mcp-server를 사용하세요. Docker Desktop이 실행 중인지 확인한 다음 실행하세요:

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

원격 HTTP 대신 Docker를 언제 선택해야 할까요? 간단히 비교해 볼게요:

지원 중단된 npm 패키지는 사용하지 마세요

이것이 가장 흔한 실수예요. 오래된 가이드 상당수가(언어를 막론하고) 여전히 npm으로 @modelcontextprotocol/server-github를 설치하라고 안내해요. 그 커뮤니티 패키지는 2025년 4월에 지원 중단되었고 - 그대로 따라 하면 연결되지 않는 서버가 되거나 알기 어려운 오류가 나요. 2026년의 올바른 방법은 원격 HTTP 또는 github/github-mcp-server 저장소(GitHub 공식 소스, 2026년 업데이트)의 공식 Docker 이미지예요.

4단계 - 확인하고 사용해 보기

서버를 추가한 뒤 "Connected"라고 표시되는지 확인하세요:

claude mcp list

github가 연결됨 상태로 보여야 해요. 다음으로 Claude Code를 열고 입력하세요:

/mcp

/mcp 명령은 지금 사용할 수 있는 GitHub 도구를 모두 나열해요. 이제 실제 프롬프트를 몇 개 시도해 보세요:

• "내 GitHub 저장소를 나열해 줘."
• "owner/repo에 'Improve the setup docs'라는 제목으로 issue를 만들어 줘."
• "이 저장소의 open 상태 pull request를 요약해 줘."

Claude가 올바른 데이터를 반환하고 issue를 만들 수 있으면 연결된 거예요.

흔한 오류 문제 해결

GitHub MCP 연결 문제는 대부분 세 가지 원인으로 좁혀져요: 잘못된 토큰이나 부족한 권한, 실수로 옛날 설치 방법 사용, 또는 서버를 추가한 뒤 Claude Code를 재시작하지 않음. 뭔가 이상하다면 아래 표에서 증상을 맞춰 보세요:

일반적인 팁: 헷갈릴 때는 claude mcp remove github를 실행하고 처음부터 다시 추가하세요 - 대부분의 설정 문제가 이걸로 해결돼요.

보안과 최소 권한(read-only, toolset)

에이전트에게 GitHub 쓰기 권한을 주는 건 편리하지만 실제 위험도 있어요: 모호한 프롬프트 하나로 Claude가 의도치 않은 issue나 PR을 만들 수 있고, 권한이 지나치게 넓은 토큰이 유출되면 많은 저장소에 영향을 줘요. 안전을 지키기 위한 몇 가지 규칙이에요:

• 최소한의 토큰을 부여하세요: 필요한 저장소만, 사용하는 권한만 선택하세요.
• 토큰을 절대 커밋하지 마세요: 토큰이 어떤 저장소에도 남지 않도록 -s user를 권장해요. 꼭 -s project를 써야 한다면, 평문으로 적지 말고 환경 변수로 토큰을 전달하세요.
• 읽기만 필요하면 read-only를 사용하세요: GitHub MCP 서버는 read-only 모드를 지원하고 개별 toolset을 켜거나 끌 수 있어요 - 검토하거나 찾아보기만 할 때는 Claude가 쓰기가 아니라 읽기만 하도록 제한하세요.
• 토큰 만료 기간을 짧게 설정하고 다 쓰면 폐기하세요.

솔직히 말하면: AI에게 쓰기 권한을 넘긴 이상 완벽하게 안전한 구성은 없어요 - 토큰의 스코프를 바짝 좁히고 중요한 작업은 꼭 두 번 확인하세요.

다음 단계: Claude Code로 git 워크플로 자동화하기

GitHub MCP가 돌아가면 자연스러운 다음 단계는, 변경의 전체 라이프사이클을 Claude에게 맡기는 거예요: 브랜치를 만들고, 규약에 맞게 커밋하고, PR을 열고, 리뷰하기. 그것을 다룬 글이 Claude Code로 git 워크플로 자동화하기 (기사가 게시되면 링크가 활성화돼요)예요.

자주 묻는 질문(FAQ)

GitHub MCP는 무료인가요?

GitHub MCP 서버 자체(원격 HTTP와 공식 Docker 이미지 모두)는 무료예요. GitHub 계정과 Personal Access Token만 있으면 돼요. 작업은 여전히 계정의 일반적인 GitHub API 레이트 리밋에 포함돼요.

Docker가 꼭 필요한가요?

아니요. 추천 방법은 원격 HTTP예요 - claude mcp add --transport http 명령 하나면 되고 Docker는 필요 없어요. Docker는 서버를 내 컴퓨터에서 로컬로 돌리고 싶을 때만 필요해요.

PAT에는 어떤 스코프가 필요한가요?

fine-grained 토큰으로는, 사용하려는 특정 저장소에 대해 최소한 Contents, Issues, Pull requests를 부여하세요. 조직 안에서 작업한다면 read:org를 추가하세요. 필요 이상으로 부여하지 마세요.

GitHub MCP 서버는 어떻게 제거하나요?

claude mcp remove github를 실행하세요. 서버를 다른 스코프로 추가했다면 제거할 때 그 스코프(예: -s user)를 다시 지정하세요.

gh CLI와는 어떻게 다른가요?

gh는 명령을 직접 하나씩 입력하는 커맨드라인 도구예요. GitHub MCP는 대화의 맥락을 바탕으로 Claude가 GitHub API를 호출하게 해요 - 자연어로 요청하면 Claude가 도구를 골라 실행하고, 같은 세션에서 다른 단계와 이어 붙일 수도 있어요.

OAuth는 이제 되나요?

2026년 8월 기준으로 Claude Code의 원격 GitHub MCP에서는 OAuth가 아직 완전히 지원되지 않으니, 연결에는 PAT가 여전히 확실하고 추천되는 방법이에요.

결론

단 네 단계 - PAT 만들기 -> 원격 HTTP로 서버 추가하기 -> claude mcp list와 /mcp로 확인하기 -> 사용해 보기 - 로 Claude Code에 자연어로 GitHub를 읽고 조작하는 능력을 부여했어요. 핵심은 이거예요: 원격 HTTP나 공식 Docker 이미지를 쓰고, 지원 중단된 npm 패키지는 피하며, 토큰은 스코프를 바짝 좁혀 어떤 저장소에도 두지 마세요. 더 빠르게 하고 싶고 스코프 제어가 덜해도 괜찮다면, 위의 /plugin install github@claude-plugins-official 명령을 시도해 볼 만해요. 기초를 더 깊이 이해하려면 MCP란 무엇이고 어떻게 동작하는지를 읽어 보고, 자동화를 더 파고들려면 Claude Code로 하는 git 워크플로 (게시되면 링크)를 보세요. /mcp 명령과 다른 슬래시 명령이 필요하세요? Claude Code의 슬래시 명령을 확인하세요.