Claude Code 커넥터 튜토리얼: 20분 만에 GitHub 리포 정리(Triage)하기

이 튜토리얼에서는 Claude 커넥터(모델 컨텍스트 프로토콜 기반)를 사용해 Claude Code를 GitHub에 연결하고, 이를 통해 오픈 소스 리포지토리를 처음부터 끝까지 분류(triage)하는 방법을 보여드립니다. 

이 워크플로는 아무것도 클론하지 않고, 벡터 스토어도 필요 없으며, 대상 리포의 어떤 행도 건드리지 않습니다. 대신 Claude Code가 커넥터를 통해 이슈를 읽고, 게시 여부를 결정하기 전에 검토할 수 있도록 산출물을 로컬 파일 시스템에 작성합니다.

이 튜토리얼을 마치면 다음을 얻게 됩니다:

• 읽기 전용 토큰으로 작동하는 Claude Code와 GitHub MCP 설정,
• 어떤 공개 리포에도 적용할 수 있는 재사용 가능한 프롬프트 모음,
• langchain-ai/langchain에 대한 완성된 트리아지 산출물(비교용).

Claude Code GitHub 커넥터(MCP)란?

Claude Code는 Anthropic의 터미널 기반 코딩 에이전트입니다. 

기본적으로 파일 시스템, 셸, git을 이미 갖추고 있습니다. Claude Code 커넥터는 이를 확장해 터미널만으로는 닿을 수 없는 외부 컨텍스트(예: GitHub 이슈, Linear 티켓, Slack 메시지, Postgres 쿼리 등)에 접근하게 해줍니다.

커넥터 프로토콜은 MCP(Model Context Protocol)라고 하며, LLM 에이전트에게 도구와 데이터를 노출하는 개방형 표준입니다. 

Anthropic은 즉시 사용 가능한 커넥터 디렉터리를 유지 관리하며, 직접 작성하거나 써드파티 MCP 서버에 연결할 수도 있습니다.

이 튜토리얼에서는 Docker로 로컬에서 실행되는 공식 GitHub MCP 서버를 사용하겠습니다. 설정의 핵심 아이디어는 다음과 같습니다:

• 클라우드 중개 없이 로컬 Docker 컨테이너로 실행되므로 자격 증명이 내 컴퓨터에만 남습니다.
• 표준 GitHub 개인 액세스 토큰(PAT)으로 인증하므로 OAuth 앱 등록이 필요 없습니다.
• 권한 범위 지정(scped permissions)을 지원합니다. 예를 들어 범위가 없는 PAT는 공개 리포에 대한 읽기 전용 접근만 허용하므로 GitHub API 레벨에서 쓰기가 불가능합니다.
• claude mcp add 명령으로 Claude Code에 노출하면, 세션마다 도구를 사용할 수 있습니다.

오픈 소스 트리아지는 읽기 작업이 많고 판단이 중요하며, 틀려도 비용이 적게 듭니다. 

50개의 이슈를 읽고 군집화하는 일은 사람에게는 지루하지만, 한 번에 모든 컨텍스트를 유지할 수 있는 모델에는 잘 맞습니다. 

또한 출력물을 먼저 로컬 파일로 작성하므로, 군집이 부정확하거나 초안이 서툴러도 비용이 들지 않으며 검토 단계에서 걸러낼 수 있습니다.

Claude Code GitHub 커넥터 튜토리얼: langchain-ai/langchain 트리아지 만들기

이 섹션에서는 Claude Code에 GitHub 커넥터를 설정하고, langchain-ai/langchain을 대상으로 네 가지 트리아지 프롬프트를 실행합니다. 이 리포는 규모가 큰 ML 프로젝트이며 이슈 트래커가 실제로 꽤 복잡합니다. 전체적으로 다음을 구현합니다:

• Docker에서 실행 중인 공식 MCP 서버를 통해 Claude Code를 GitHub에 연결,
• 커넥터를 구조적으로 읽기 전용으로 만들기 위해 범위가 없는 PAT 사용,
• 결과를 로컬 파일로 저장하는 트리아지 프롬프트 실행,
• Claude가 이슈를 중복으로 묶기를 거부한 사례를 포함해 출력물 검토.

이제 단계별로 진행하겠습니다.

1단계: Claude Code와 Docker 사전 준비물 설치

커넥터를 설정하기 전에 다음 세 가지가 필요합니다:

• Claude Code: Anthropic의 공식 설치 가이드에서 설치할 수 있습니다.
• Docker Desktop: 공식 GitHub MCP 서버는 컨테이너에서 실행되므로 Docker가 설치되어 실행 중이어야 합니다.
• GitHub 계정: 다음 단계에서 PAT를 생성하려면 필요합니다.

모든 준비가 끝나면 Docker가 실행 중인지 확인하세요:

docker info | head -5

Docker가 설치되어 있지 않거나 데몬이 올라오지 않았다면 "Cannot connect to the Docker daemon" 오류가 표시됩니다. macOS에서는 다음으로 Docker Desktop을 실행하세요:

open -a Docker

Docker Desktop은 완전히 준비되는 데 15~60초가 걸리며, 그 사이에는 docker info가 계속 오류를 냅니다. 수동으로 확인하는 대신, 데몬이 올라올 때까지 폴링하는 간단한 대기 원라이너를 사용하세요:

until 

docker info >/dev/null 2>&1; do sleep 2; echo "waiting..."; done && echo "Docker ready"

Docker ready가 출력되면 다음으로 넘어가세요.

2단계: 읽기 전용 GitHub 토큰 생성

Docker 설정을 마쳤다면, 다음으로 github.com/settings/tokens로 이동해 새 클래식 토큰을 생성하세요.

참고: 모든 범위(scope)를 선택하지 않은 상태로 두세요. 범위가 없는 토큰도 GitHub API를 통해 공개 리포지토리를 읽을 수 있으며, 우리 에이전트에는 이 정도면 충분합니다. 어떤 범위도 선택하지 않으면, GitHub에서는 토큰으로 쓰기/수정/삭제가 물리적으로 불가능합니다. 이는 에이전트의 동작에 대한 약속이 아니라 GitHub 측에서 강제하는 하드 보장입니다.

토큰을 생성 직후 복사해 저장한 다음, 셸에서 내보내세요:

export GITHUB_PERSONAL_ACCESS_TOKEN="ghp_your_token_here"

이미 Claude Code 세션 안에 있다면, ! 프리픽스를 사용해 셸에서 직접 export 명령을 실행하고 싶을 수 있습니다(예: ! export GITHUB_PERSONAL_ACCESS_TOKEN="..."). 

하지만 !는 임시 서브셸을 생성하므로, 명령이 끝나는 순간 변수가 사라져 Claude가 이를 인식하지 못합니다.

모델 프롬프트에 토큰을 붙여넣지 않고 안전하게 설정하려면 두 가지 방법이 있습니다:

1. /exit를 입력해 Claude를 종료한 뒤, 일반 터미널에서 export 명령을 실행하고 Claude를 재시작하세요.
2. 또는 작업 디렉터리에 로컬 .env 파일로 토큰을 저장하세요. Claude Code는 시작 시 이를 자동으로 읽습니다.

토큰 자체를 에코하지 않고 두 가지 준비가 완료되었는지 확인하세요:

docker info | head -3
echo "Token set: ${GITHUB_PERSONAL_ACCESS_TOKEN:+yes}"

두 번째 명령은 변수가 존재하면 Token set: yes를, 비어 있으면 Token set: (콜론 뒤에 아무 것도 없음)을 출력합니다. 

이는 토큰을 직접 에코하는 것보다 안전합니다. 평문으로 셸 히스토리에 남을 가능성이 전혀 없기 때문입니다.

3단계: Claude Code에 GitHub 커넥터 등록

공식 GitHub MCP 서버는 Docker 이미지로 제공됩니다. 

이를 claude mcp add로 Claude Code에 등록합니다:

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

여기서 -e 플래그가 두 번 등장하는 것은 오타가 아닙니다:

• 첫 번째 -e(-- 앞)는 Claude Code가 실행하는 MCP 프로세스의 환경 변수를 설정합니다.
• 두 번째 -e (docker run 인자 안)는 해당 변수를 컨테이너로 전달하도록 Docker에 지시합니다.

둘 중 하나라도 빠져 토큰이 비어 있는 상태로 컨테이너가 시작되면 GitHub API 인증에 실패합니다.

커넥터가 정상 등록되었는지 확인하려면:

claude mcp list

다음과 같이 보여야 합니다:

github — docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server —  Connected

만약 Failed to connect가 보인다면, 가장 흔한 원인은 Docker가 실행 중이 아니거나 claude mcp add를 실행한 동일한 셸에서 GITHUB_PERSONAL_ACCESS_TOKEN이 export되지 않았기 때문입니다.

4단계: 연결 상태 점검

이제 GitHub 토큰을 설정했습니다. 작업 디렉터리를 만들고 Claude Code CLI를 열어보겠습니다:

mkdir demo && cd demo
claude

claude 명령은 현재 디렉터리에서 대화형 세션을 시작합니다. 

트리아지 중 Claude가 작성하는 모든 파일은 이곳에 생성됩니다. 

그다음, 커넥터가 사용 중인지 확인하기 위해 간단한 읽기 전용 질문을 해보세요:

Using the GitHub MCP connector, fetch the 5 most recently updated open issues in langchain-ai/langchain. Just list titles and numbers.

Claude Code가 GitHub 도구를 처음 사용할 때는 승인을 요청합니다. 

list_issues, get_issue, search_issues 등 읽기 전용 도구는 승인하세요. 

만약 Claude가 MCP 도구 대신 공개 GitHub API에 curl로 폴백한다면 커넥터가 로드되지 않은 것입니다. 세션을 종료 후 다시 시작하세요.

성공하면 다음과 같은 결과가 반환됩니다:

MCP를 통해 실제 이슈 번호가 반환되는 것을 확인했다면, 이제 실제 트리아지를 실행할 준비가 된 것입니다.

5단계: 백로그 요약 생성

준비 운동은 순수 읽기 전용 작업입니다. 먼저 이슈 트래커에 무엇이 있는지 지도를 얻고자 합니다.

Prompt:
Using the GitHub MCP connector, pull the 50 most recently updated open issues from langchain-ai/langchain. 
Read their titles, bodies, and labels. Group them by likely area — bugs, feature requests, documentation, questions, and "needs more info." 
For each group, give me a count and 3-5 representative issue numbers with a one-line reason. Save as backlog-summary.md in the current directory.

Claude Code는 커넥터를 통해 이슈를 가져와 검토하고, 대표 이슈 번호와 함께 영역별로 묶은 마크다운 파일을 작성합니다. 이 파일만으로도 유지관리자는 60초 만에 훑어보고 한 주의 이슈 양상을 파악할 수 있습니다.

6단계: 중복 후보 표시

중복 감지는 에이전트가 진가를 발휘하는 부분입니다. 

50개의 이슈를 처음부터 끝까지 읽고 근본 원인별로 군집화하는 일은 사람에겐 번거롭지만, 모델은 전체를 컨텍스트에 담아 키워드 검색으로는 놓칠 중복을 찾아낼 수 있습니다.

Prompt:
From the same 50 issues you already pulled, identify clusters of likely duplicates: issues describing the same underlying problem, even if titles differ. For each cluster, output issue numbers, a one-sentence shared-problem description, and confidence (high/medium/low). Save as duplicate-candidates.md.

제가 실행했을 때 Claude가 실제로 만든 결과는 다음과 같습니다:

이 출력물에서 가장 흥미로운 부분은 클러스터 2~4입니다. 

순진한 키워드 기반 중복 탐지기는 네 개 클러스터 모두를 중복으로 닫았을 것입니다. 

하지만 Claude는 이를 중복이라 부르기를 명시적으로 거부했습니다. 

같은 서브시스템을 공유하지만 근본 원인이 다른 컴포넌트 클러스터로 표시했고, 실제로 닫아야 할 것(클러스터 1만 해당)과 공동으로 분류하되 열어둬야 할 것을 구분해 알려줬습니다.

이는 신중한 휴먼 트리아저에게 기대하는 동작이며, 바로 그래서 로컬 파일로 작성 후 검토하는 패턴이 한 단계를 더 거치더라도 가치가 있습니다. 

이 과정을 GitHub API에 바로 연결해 Claude가 표시한 것을 자동으로 닫았다면, 실제 버그 세 건을 닫아버렸을 것입니다.

7단계: 검토 후 게시 여부 결정

이것이 로컬 파일 패턴의 핵심입니다. 

GitHub에 어떤 것도 반영되기 전에, Claude가 저장한 각 .md 파일을 확인해 그룹화가 본인의 직관과 맞는지 검토하세요. 

고신뢰 클러스터가 실제로 중복처럼 보이나요? 초안 응답 2~3개를 읽어보고 본인 문체와 어울리는지 확인하세요.

실제로 코멘트를 게시하거나 라벨을 적용하고자 한다면 두 가지 선택지가 있습니다:

• 수동: 초안을 직접 GitHub에 붙여넣으면 됩니다. 타인의 리포에서 일회성 트리아지를 하는 경우, 이 방법이 적절한 선택인 경우가 많습니다.
• 본인 소유 리포에서 쓰기 권한 허용: repo 범위가 있는 별도의 PAT를 생성해 별도 커넥터 항목(예: github-write)으로 추가하고, 라벨 적용과 코멘트 게시를 요청하도록 프롬프트를 재실행하세요. Claude Code는 쓰기 도구를 처음 사용할 때마다 승인 요청을 표시합니다.

쓰기 경로에서의 핵심 안전 장치는 읽기 토큰과 쓰기 토큰을 분리하는 것입니다. 

결론

이 튜토리얼에서는 MCP를 통해 Claude Code를 GitHub에 연결하고, 이를 사용해 실제 오픈 소스 리포지토리를 처음부터 끝까지 트리아지하는 방법을 시연했습니다. 

맞춤형 GitHub 봇을 만들거나 웹훅을 연결하는 대신, 공식 GitHub MCP 서버를 통해 이슈를 읽고 네 가지 트리아지 산출물을 로컬 파일로 작성한 뒤, 게시 여부를 결정하기 전에 모든 내용을 검토합니다.

더 넓게 보면, 커넥터는 Claude Code를 코딩 에이전트에서, 여러분의 도구를 읽고 검토용 작업을 준비해 주는 도구로 바꿔줍니다. 

기본값으로는 여러분이 확인할 때까지 그 작업을 로컬에 유지하는 것이 옳습니다. 이 패턴을 신뢰하게 되면, 실수 비용이 낮은 곳부터 선택적으로 에이전트에게 실행을 맡길 수 있습니다.

여기서부터 다음과 같이 확장할 수 있습니다:

• 본인 소유 리포에 쓰기 가능한 커넥터를 추가해, 검토 후 라벨과 코멘트가 자동 적용되도록 설정
• Linear 또는 Slack 커넥터를 연동해 트리아지 결정을 팀 워크플로와 동기화
• 프롬프트를 예약된 CI 작업으로 전환해 주간 트리아지 PR을 자동 생성
• 또는 위 프롬프트를 어떤 리포 URL에도 작동하는 재사용 가능한 Claude Code 슬래시 커맨드로 일반화