“내 GitHub 저장소를 Claude에 연결하고 싶은데, 방법이 너무 많아서 뭘 써야 할지 모르겠다.” 클로드 깃허브 연동을 처음 시도하면 대부분 이 지점에서 막힙니다. 커넥터, Claude Code, GitHub Actions, MCP까지 이름만 네 가지입니다.
결론부터 말하면, 이 네 가지는 하는 일이 다릅니다. 코드를 읽기만 할 건지, 직접 수정하고 커밋할 건지, PR이 올라올 때마다 자동으로 리뷰할 건지에 따라 쓸 방법이 갈립니다. 하나씩 실제 화면과 설정을 보면서 정리합니다.
클로드 깃허브 연결, 방법이 왜 여러 개인가
| 방법 | 환경 | 주요 용도 | 코드 수정 가능 |
|---|---|---|---|
| Projects GitHub 커넥터 | Claude 웹(claude.ai) | 저장소 코드를 읽고 질문 | 불가 |
| Claude Code + 로컬 Git | 터미널(CLI) | 코드 읽기, 수정, 커밋, PR | 가능 |
| GitHub App + Actions | GitHub 저장소 | PR 리뷰, 이슈 응답 자동화 | 가능 |
| MCP GitHub 서버 | Claude Desktop / Code | GitHub API 직접 호출 | 가능(API 범위 내) |
네 가지를 한꺼번에 설정할 필요는 없습니다. 자기 상황에 맞는 것만 골라 쓰면 됩니다.
Claude Projects에서 GitHub 커넥터로 연결하기
코드를 수정할 필요 없이, Claude에게 저장소 코드를 읽히고 질문만 하고 싶다면 가장 간단한 방법입니다.
설정 순서:
- claude.ai에서 프로젝트를 하나 만듭니다.
- 오른쪽 패널의 추가 버튼을 클릭합니다.
- 드롭다운에서 GitHub를 선택합니다.
- GitHub 계정을 연결하고, 원하는 저장소와 폴더를 지정합니다.
연결이 완료되면 해당 프로젝트에서 대화할 때마다 Claude가 지정된 저장소의 코드를 참조합니다. “이 프로젝트의 인증 로직이 어떻게 되어 있어?”처럼 질문하면 실제 코드를 기반으로 답합니다.
다만 이 방식은 읽기 전용입니다. Claude가 코드를 수정하거나 커밋을 만들지는 못합니다. 동기화도 연결 시점의 코드를 가져오는 구조이므로, 저장소가 업데이트되면 프로젝트에서 다시 동기화해야 최신 코드가 반영됩니다.
Claude Code에서 Git 저장소 직접 사용하기
코드를 읽는 것뿐 아니라 수정, 커밋, PR 생성까지 하려면 Claude Code를 씁니다. Claude Code는 터미널에서 실행하는 CLI 도구이고, 로컬 Git 저장소 위에서 바로 작업합니다.
bash cd your-project claude
프로젝트 폴더로 이동해서 claude를 실행하면 됩니다. Claude Code는 해당 디렉터리의 파일 구조를 자동으로 읽습니다. 별도의 GitHub 연동 설정이 필요 없습니다. 로컬에 Git이 설정되어 있으면 그대로 사용합니다.
위 화면이 실제 작업 흐름입니다. “이 Git 저장소에서 README.md에 섹션 하나만 추가해줘”라고 요청하면, Claude Code가 파일을 찾고, 변경 내용의 diff를 보여준 뒤, 승인을 요청합니다. 확인 후 “이제 커밋해줘”라고 하면 커밋 메시지까지 자동으로 만들어 줍니다.
핵심은 Claude Code가 파일 수정 전에 항상 승인을 요청한다는 점입니다. diff를 확인하고 수락하거나 거절할 수 있으므로, 의도하지 않은 변경이 바로 반영되지는 않습니다.
이 방식은 내 컴퓨터에서 직접 작업하는 구조입니다. Claude Code가 GitHub API를 호출하는 것이 아니라, 로컬 Git 명령어를 실행합니다. git push 권한은 내 로컬 Git 설정(SSH 키 또는 credential)을 그대로 따릅니다.
GitHub App 설치와 Actions 자동화
PR이 올라올 때마다 Claude가 자동으로 코드 리뷰를 하게 하거나, 이슈에서 @claude로 호출해 작업을 시키려면 GitHub App + GitHub Actions 조합을 씁니다.
GitHub App 설치
GitHub Marketplace에서 Claude GitHub App을 찾아 Install 버튼을 누릅니다. 설치 과정에서 권한 범위를 선택합니다.
- All repositories: 계정의 모든 저장소에 접근 허용
- Only select repositories: 특정 저장소만 선택
권한은 커밋 상태 읽기(Read), 코드·PR·이슈 읽기/쓰기(Read and write)가 포함됩니다. Install & Authorize를 클릭하면 Claude 쪽으로 리다이렉트되면서 연결이 완료됩니다.
@claude 호출용 Actions 워크플로우
PR이나 이슈 댓글에서 @claude를 쓰면 Claude가 응답하도록 하는 워크플로우입니다. 저장소에 .github/workflows/claude.yml 파일을 만들고 아래 내용을 넣습니다.
“`yaml name: Claude Code
on: issue_comment: types: [created] pull_request_review_comment: types: [created]
jobs: claude: if: contains(github.event.comment.body, ‘@claude’) runs-on: ubuntu-latest permissions: contents: write pull-requests: write issues: write id-token: write actions: read steps:
- uses: actions/checkout@v6
with: fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} “`
ANTHROPIC_API_KEY는 저장소의 Settings → Secrets에 미리 등록해야 합니다. 설정 후 PR 댓글에 @claude review this change처럼 쓰면 Claude가 같은 PR에 리뷰 코멘트를 작성합니다.
자동 PR 리뷰 워크플로우
@claude를 매번 호출하지 않고, PR이 열리거나 업데이트될 때 자동으로 리뷰하게 할 수도 있습니다.
“`yaml name: Claude Code PR Review
on: pull_request: types: [opened, synchronize, ready_for_review, reopened]
jobs: claude-review: runs-on: ubuntu-latest permissions: contents: read pull-requests: read issues: read id-token: write steps:
- uses: actions/checkout@v6
with: fetch-depth: 1
- uses: anthropics/claude-code-action@v1
with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} plugin_marketplaces: “https://github.com/anthropics/claude-code.git” plugins: “code-review@claude-code-plugins” prompt: >- /code-review:code-review –comment ${{ github.repository }}/pull/${{ github.event.pull_request.number }} claude_args: >- –allowedTools “mcp__github_inline_comment__create_inline_comment” “`
여기서 --comment 옵션이 중요합니다. 이 옵션이 있어야 Claude가 PR에 실제 리뷰 코멘트를 작성합니다. 없으면 결과가 GitHub Actions 로그에만 남고 PR에는 아무것도 표시되지 않습니다.
MCP는 언제 필요한가
위 방법으로 대부분의 상황은 해결됩니다. 그런데 MCP(Model Context Protocol)라는 말도 자주 보입니다. 언제 쓸까요?
MCP GitHub 서버는 Claude가 GitHub API를 직접 호출할 수 있게 해주는 별도 연결입니다. 이슈 목록 조회, 저장소 검색, 파일 내용 읽기 같은 GitHub API 기능을 Claude의 도구로 노출하는 구조입니다.
Claude Desktop에서는 로컬에 Docker로 MCP 서버를 띄우는 방식이 기본입니다.
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": "YOUR_GITHUB_PAT" } } } }
설정 파일 위치는 환경마다 다릅니다.
| 환경 | MCP 설정 파일 |
|---|---|
| Claude Desktop | claude_desktop_config.json |
| Claude Code (개인) | ~/.claude.json |
| Claude Code (팀 공유) | 프로젝트 루트 .mcp.json |
Claude Code에서는 Docker 없이 GitHub Remote MCP에 HTTP로 직접 연결할 수도 있습니다.
bash claude mcp add-json github \ '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer YOUR_GITHUB_PAT"}}'
팀 프로젝트라면 .mcp.json에 설정을 넣고 Git에 올리되, PAT는 환경변수로 분리하는 방식이 안전합니다.
json { "mcpServers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/", "headers": { "Authorization": "Bearer ${GITHUB_PAT}" } } } }
이렇게 하면 .mcp.json에는 비밀 값이 없으므로 Git에 올릴 수 있고, 각 개발자가 자기 컴퓨터에 GITHUB_PAT 환경변수만 설정하면 됩니다.
MCP는 Claude가 GitHub API를 “도구”로 쓸 수 있게 하는 것이지, Claude Code의 로컬 Git 작업을 대체하는 것이 아닙니다. 로컬에서 코드를 수정하고 커밋하는 작업은 Claude Code만으로 충분합니다. 여러 저장소의 이슈를 한꺼번에 조회하거나, Claude Desktop에서 GitHub 데이터를 참조해야 할 때 MCP가 필요합니다.
Private 저장소와 권한 정리
Private 저장소를 연결할 때 방법마다 인증 방식이 다릅니다.
| 방법 | Private repo 접근 방식 |
|---|---|
| Projects 커넥터 | GitHub OAuth 연결 시 private repo 접근 권한 부여 |
| Claude Code | 로컬 Git 설정(SSH 키, credential helper)을 그대로 사용 |
| GitHub App | App 설치 시 저장소 범위 선택(All 또는 특정 저장소) |
| MCP | GitHub Personal Access Token에 부여된 scope에 따름 |
GitHub App 설치 시 Only select repositories를 선택하면 지정한 저장소에만 Claude가 접근합니다. 조직 저장소라면 조직 관리자가 App 설치를 승인해야 합니다.
상황별 추천
“코드를 읽고 질문만 하고 싶다” → Claude Projects의 GitHub 커넥터. 설정이 가장 간단하고, 코드를 건드릴 위험이 없습니다.
“코드를 직접 수정하고 커밋하고 싶다” → Claude Code. 터미널에서 cd와 claude만 치면 바로 작업할 수 있습니다.
“PR마다 자동으로 리뷰받고 싶다” → GitHub App + Actions. 워크플로우 YAML을 한 번 설정하면, 이후에는 PR이 열릴 때마다 자동으로 동작합니다.
“Claude Desktop에서 GitHub 데이터를 참조하고 싶다” → MCP GitHub 서버. 이슈, PR 목록, 파일 내용을 Claude의 대화 안에서 조회할 수 있습니다.
네 가지를 동시에 쓸 수도 있지만, 처음이라면 자기 목적에 맞는 것 하나만 설정하고 익숙해진 뒤에 확장하는 편이 낫습니다.
