처음 뵙겠습니다, 시히로입니다.

이번에는 GitHub 조작을 CLI로 완결합니다.

"Issue #5를 구현해서 PR을 올려줘"

이렇게 입력하면, Claude가 자동으로 브랜치를 생성하고, 코드를 작성하고, 테스트를 통과한 뒤, PR을 만들어 가져옵니다.

개발 현장에 따라서는 금지되어 있는 경우도 있으므로, 사내 규칙 등을 따르도록 합시다. 잘 모를 때는 상사에게 상담을 (사고를 쳤을 때 저는 책임을 질 수 없습니다.)

Claude Code에 GitHub MCP 서버를 연결하면, 자연어만으로 GitHub 조작이 가능해집니다.

MCP (Model Context Protocol) 는 Claude가 외부 도구와 연동하기 위한 표준 프로토콜입니다.

한마디로 말하면 "Claude에게 GitHub나 Slack 등 외부 도구를 다루게 하는 메커니즘"입니다.

"Claude Code로 코드를 작성하게 하는" 단계는 이미 여러분 모두 하고 계실 것이라 생각하므로, "GitHub 조작까지 맡기는 것"이 이번 테마입니다.

먼저 GitHub 토큰이 필요합니다.

Classic PAT는 사용하지 마세요!

Classic PAT를 사용하면 계정 전체의 리포지토리(Repository)에 권한이 미칩니다. Claude가 토큰을 사용하여 무언가 사고를 쳤을 때, 피해가 모든 리포지토리로 확산됩니다. Fine-grained PAT를 사용하면 특정 리포지토리와 조작으로만 범위를 좁힐 수 있습니다.

Settings > Developer settings > Personal access tokens > Fine-grained tokens

을 열고, 「Generate new token」을 클릭합니다.

권한은 이것만 부여합니다.

「Repository access」는 「Only select repositories」로 하여, 대상 리포지토리만 선택해 주세요.

모든 곳에 권한을 줄 필요는 없습니다.

※ 최소 권한의 원칙이라는 것입니다.

토큰이 생성되면 즉시 복사합니다. 이 페이지를 벗어나면 두 번 다시 표시되지 않습니다.

현재 권장되는 것은 GitHub 공식 MCP 서버 (github/github-mcp-server) 입니다. Docker로 구동합니다.

Docker Desktop을 설치하여 실행해 두세요.

프로젝트 루트에 .mcp.json을 생성합니다.

{
"mcpServers": {
"github": {
...

환경 변수로 관리하는 경우에는 env의 값을 "${GITHUB_PERSONAL_ACCESS_TOKEN}"로 바꿔주세요.

.mcp.json을 그대로 git에 커밋하면 토큰이 유출됩니다. .gitignore에 추가해 주세요.

.mcp.json

Claude Code를 실행하고 /mcp라고 입력합니다.

> /mcp
MCP Server Status:
● github (connected)
...

connected라고 나오면 OK입니다.

MCP를 연결하는 것만으로는 Claude는 리포지토리의 규칙을 아무것도 모릅니다.

• main에 직접 커밋하지 마라
• 테스트가 실패하면 멈춰라
• 브랜치명은 이 형식으로

이러한 규칙은 CLAUDE.md에 작성하여 전달해야 합니다.

「CLAUDE.md」는 Claude Code가 세션 시작 시 자동으로 읽어들이는 파일입니다.

여기에 적은 내용은 매번 구두로 전달하지 않아도 기능합니다.

프로젝트 루트에 CLAUDE.md를 생성해 주세요.

# 프로젝트 개요
이 리포지토리는 ○○ 서비스의 백엔드 API.
- 언어: TypeScript / Node.js
...

/init 명령어로 템플릿을 자동 생성할 수 있지만, 범용적인 기술이 대량으로 들어옵니다. 300행을 넘어가면 컨텍스트(Context)를 압박하여 정확도가 떨어지므로, 내용을 덜어내는 용도로 사용하는 것을 추천합니다.

이런 Issue가 있다고 가정해 봅시다.

Issue #5: 사용자 목록 API에 페이지네이션 (Pagination) 기능 추가
현재 GET /users는 모든 사용자를 반환하고 있음.
?page=1&limit=20와 같은 쿼리 파라미터 (Query Parameter)로 대응해 주길 바람.

Claude Code에서 이렇게 입력하기만 하면 됩니다.

> Issue #5를 읽고, 구현해서 PR을 만들어 주세요.

그다음은 Claude가 알아서 합니다.

Claude: Issue #5를 확인했습니다. 다음과 같은 계획으로 구현하겠습니다.
1. `src/controllers/userController.ts`의 `getUsers` 함수 수정
2. `page`·`limit` 쿼리 파라미터 유효성 검사 (Validation) 추가
...

PR URL이 반환되었습니다. 브라우저는 아직 열지 않았습니다.

PR을 만들려고 했더니 403 Forbidden이 뜹니다.

"Pull requests: Read & Write"에 체크하는 것을 잊었을 때가 있습니다.

권한을 나중에 변경하는 UI가 있지만, 반영되는 데 시간이 걸릴 수 있습니다.

이럴 때는 빠르게 재발급하는 것이 더 빠릅니다.

main 브랜치로의 직접 커밋은 피해주세요.

"피해주세요"라고 하면 상황에 따라 무시될 수 있습니다.

main 브랜치로의 직접 커밋은 금지. 반드시 feature/ 브랜치를 생성할 것.

CLAUDE.md의 금지 사항은 "부탁"이 아니라 "제약 (Constraint)"으로서 작성해야 합니다.

# NG
4. `npm run test`를 실행한다
# OK
...

실패하면 멈추라는 내용까지 쓰지 않으면 Claude는 커밋을 계속합니다.

최초 실행 시에는 ghcr.io/github/github-mcp-server 이미지 pull이 실행되므로 몇 분 정도 걸릴 수 있습니다.

미리 pull 해두면 기동 속도가 빨라집니다.

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

두 번째 실행부터는 캐시 (Cache)가 사용되므로 대기 시간이 거의 사라집니다.

가장 컸던 변화는 브라우저를 여는 동작이 사라졌다는 점이었습니다.

Issue를 확인하기 위해 브라우저를 열고, 터미널로 돌아오고, 다시 GitHub를 열어 PR을 만드는... 이러한 왕복 과정이 전부 터미널의 하나의 세션 안에서 끝납니다.

"Claude Code로 코드를 작성하게 한다" 단계에 머물러 있던 분들은 꼭 GitHub MCP를 추가해 보세요. 코딩 이외의 작업이 사라지면 정말 편해집니다.

• GitHub MCP Server 공식 리포지토리 (github/github-mcp-server)
• Model Context Protocol 공식 문서
• Claude Code 공식 문서
• josix/awesome-claude-md (CLAUDE.md 사례 모음)

도움이 되었다면

좋아요와 저장(Stock)을 해주시면 큰 힘이 됩니다! 🙏