콘텐츠로 이동
Bosn Notes
Blog
Blog

Claude Code와 Codex에서 GitHub MCP 설정하는 방법

등록일

Overview

섹션 제목: “Overview”

GitHub 저장소 한 곳을 Claude Code와 Codex에서 읽고 수정하려면, 해당 저장소만 선택한 Fine-grained PAT를 만든 뒤 GitHub Remote MCP에 연결한다. 접근할 저장소와 작업 권한은 PAT에서 제한한다. MCP를 프로젝트 범위로 등록하는 것은 그 프로젝트에서 서버를 사용하도록 설정하는 것이며, PAT의 GitHub 접근 범위를 대신 제한하지 않는다.

이 문서는 macOS의 zsh 환경에서 GITHUB_PAT_TOKEN을 두 클라이언트가 공유하는 예시다. GitHub Remote MCP 주소는 https://api.githubcopilot.com/mcp/이다.

1) GitHub PAT 발급

섹션 제목: “1) GitHub PAT 발급”

GitHub의 Settings → Developer settings → Personal access tokens → Fine-grained tokens에서 토큰을 만든다.

항목값
Repository accessOnly select repositories에서 사용할 저장소 한 곳 선택
Contents파일을 수정할 경우 Read and write
Issues이슈를 작성하거나 수정할 경우 Read and write
Pull requestsPR을 작성하거나 수정할 경우 Read and write
MetadataRead-only

필요한 작업에 맞춰 권한을 선택한다. 이슈 조회만 필요하다면 쓰기 권한까지 줄 필요는 없다. 조직 저장소는 조직 정책에 따라 토큰 승인이 필요할 수도 있다.

토큰은 다시 확인하기 어려우므로 발급 직후 안전한 곳에 보관한다. 아래 예시의 github_pat_...는 실제 토큰으로 바꾸되, 토큰을 프로젝트 설정 파일이나 Git 저장소에 기록하지 않는다.

2) 환경변수 준비

섹션 제목: “2) 환경변수 준비”

예를 들어 로컬 ~/.zshrc에 다음 줄을 추가한다.

터미널 창
export GITHUB_PAT_TOKEN="github_pat_..."

새 셸을 열거나 source ~/.zshrc로 적용한다. 토큰 값을 출력하지 않고 설정 여부만 확인한다.

터미널 창
test -n "$GITHUB_PAT_TOKEN" && echo "PAT OK" || echo "PAT MISSING"

~/.zshrc에도 토큰이 평문으로 저장되므로 파일을 공유하거나 저장소에 추가하지 않는다.

3) Claude Code에 연결

섹션 제목: “3) Claude Code에 연결”

프로젝트에서만 사용

섹션 제목: “프로젝트에서만 사용”

프로젝트 루트에 .mcp.json을 작성한다.

{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {
        "Authorization": "Bearer ${GITHUB_PAT_TOKEN}"
      }
    }
  }
}

Claude Code는 .mcp.json의 HTTP headers에서 ${GITHUB_PAT_TOKEN}을 환경변수로 확장한다. 이 파일을 공유하기 전에는 실제 PAT가 들어 있지 않은지 확인한다. 프로젝트 범위 서버는 처음 사용할 때 승인 화면이 표시될 수 있다.

모든 프로젝트에서 사용

섹션 제목: “모든 프로젝트에서 사용”

사용자 범위에 같은 서버를 등록하려면 다음 명령을 사용한다. JSON을 작은따옴표로 감싸 셸이 등록 시점에 토큰을 실제 값으로 바꾸지 않게 한다.

터미널 창
claude mcp add-json --scope user github \
  '{"type":"http","url":"https://api.githubcopilot.com/mcp/","headers":{"Authorization":"Bearer ${GITHUB_PAT_TOKEN}"}}'

사용자 범위 서버는 모든 프로젝트에서 사용할 수 있다. 이미 같은 이름의 서버를 등록했다면 범위별 설정을 확인한다.

4) Codex에 연결

섹션 제목: “4) Codex에 연결”

프로젝트에서만 사용

섹션 제목: “프로젝트에서만 사용”

프로젝트 루트의 .codex/config.toml에 다음 내용을 추가한다.

[mcp_servers.github]
url = "https://api.githubcopilot.com/mcp/"
bearer_token_env_var = "GITHUB_PAT_TOKEN"

Codex는 bearer_token_env_var에 지정된 환경변수 이름을 읽어 Authorization Bearer 토큰으로 사용한다. 프로젝트 설정은 Codex가 해당 프로젝트를 신뢰할 때 로드된다.

모든 프로젝트에서 사용

섹션 제목: “모든 프로젝트에서 사용”

같은 TOML 설정을 ~/.codex/config.toml에 추가하거나 CLI로 등록한다.

터미널 창
codex mcp add github \
  --url https://api.githubcopilot.com/mcp/ \
  --bearer-token-env-var GITHUB_PAT_TOKEN

CLI 등록은 사용자 설정에 저장된다. 프로젝트에서만 사용할 때는 .codex/config.toml을 직접 작성한다.

5) 연결 확인

섹션 제목: “5) 연결 확인”
터미널 창
claude mcp list
claude mcp get github
codex mcp list
codex mcp get github

각 클라이언트의 대화 화면에서는 /mcp로 연결 상태를 확인한다. 목록에 설정이 보이는 것과 실제 GitHub API 호출 성공은 다르므로, 현재 저장소의 열린 이슈 조회도 요청해 본다. 쓰기 권한은 필요한 경우에만 테스트 이슈 생성 등으로 확인한다.

등록을 제거하려면 해당 범위의 설정 파일에서 github 항목을 삭제한다. 사용자 범위에 CLI로 등록한 서버는 claude mcp remove github 또는 codex mcp remove github로 제거할 수 있다.

Notes

섹션 제목: “Notes”

Codex 0.157.1에서 관찰한 연결 실패

섹션 제목: “Codex 0.157.1에서 관찰한 연결 실패”

초안을 작성한 환경(macOS Ventura 13.7.8, Claude Code 2.1.274, Codex 0.157.1)에서는 프로젝트 .codex/config.toml로 등록한 GitHub MCP가 일반 codex 실행 시 /mcp에서 failed로 표시됐다. 같은 프로젝트에서 codex -c log_dir=/tmp/codex-log로 실행하면 connected가 표시됐다. log_dir을 프로젝트 설정 파일에 추가하는 방법은 해결되지 않았다.

이는 당시 환경에서 관찰한 임시 우회 사례이며 원인이 확인된 해결책은 아니다. 같은 증상이 나면 먼저 환경변수, PAT 권한, 프로젝트 신뢰 여부를 확인하고, 현재 Codex 버전에서도 재현되는지 확인한다. 해당 버전에서만 우회가 필요하면 다음 명령으로 실행할 수 있다.

터미널 창
codex -c log_dir=/tmp/codex-log

매번 필요한 경우에만 셸 alias로 등록한다. 연결 문제가 사라지면 alias를 제거한다.

터미널 창
alias codex='codex -c log_dir=/tmp/codex-log'

실제 PAT가 포함된 .mcp.json이나 다른 설정 파일을 원격 저장소에 올렸다면, 해당 PAT를 폐기하고 새로 발급한다.

참고 문서

섹션 제목: “참고 문서”