github-mcp-server

GitHub 저장소를 Claude Code(또는 MCP 호환 클라이언트)에 stdio로 노출하는 최소한의 읽기 전용 MCP 서버입니다.

노출되는 도구

• list_repos(owner?, include_forks?, limit?) - 내 저장소(또는 다른 소유자의 공개 저장소) 목록 조회

• get_repo_info(owner, repo) - 단일 저장소의 메타데이터

• list_directory(owner, repo, path?, ref?) - 저장소의 파일 트리 탐색

• read_file(owner, repo, path, ref?, max_bytes?) - 텍스트 파일 내용 읽기

• get_readme(owner, repo, ref?) - 저장소의 README 가져오기

• search_code(query, owner?, repo?, limit?) - 코드 검색(선택적으로 내 저장소로 범위 제한)

• list_commits(owner, repo, path?, limit?) - 최근 커밋 기록

모든 것이 읽기 전용입니다. 쓰기, 생성, 삭제 엔드포인트는 노출되지 않습니다.

Related MCP server: github-mcp-tool

설정

1. GitHub Personal Access Token 생성(세분화된(fine-grained) 토큰 권장): GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens -> Generate new token.

   • Repository access: Claude가 읽도록 허용할 저장소 선택(또는 "All repositories")

   • Permissions: Contents: Read-only, Metadata: Read-only(search_code를 사용하려면 Code search: Read-only 추가)

2. 의존성 설치:

cd github-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. 토큰 설정(스크립트에 하드코딩하거나 어디에도 커밋하지 마세요):

export GITHUB_TOKEN=github_pat_xxxxxxxxxxxx

영구적으로 유지하려면 해당 줄을 ~/.zshrc / ~/.bashrc에 추가하거나, direnv 같은 도구로 .env 파일을 사용하세요. 단, gitignore에 포함해야 합니다.

4. Claude Code CLI에 서버 등록:

claude mcp add github-repos -- python3 /absolute/path/to/github-mcp-server/server.py

(venv를 사용했다면 venv의 python을 지정하세요: /absolute/path/to/github-mcp-server/.venv/bin/python3)

서버는 환경에서 GITHUB_TOKEN을 읽으므로, claude를 실행하는 셸에서 export하거나 명시적으로 전달하세요:

claude mcp add github-repos --env GITHUB_TOKEN=github_pat_xxxxxxxxxxxx -- python3 /absolute/path/to/github-mcp-server/server.py

5. 연결 확인:

claude mcp list

연결된 항목으로 github-repos가 표시되어야 합니다. 그런 다음 Claude Code 세션에서 "내 저장소 목록을 보여줘" 또는 "내 flight-delay-prediction 저장소의 README를 읽어줘" 같은 요청을 하면 Claude가 이 도구들을 호출합니다.

로컬 스모크 테스트(클라이언트 없이)

python3 -c "
import os
os.environ['GITHUB_TOKEN'] = 'github_pat_xxx'
from server import list_repos
print(list_repos())
"

참고 사항 / 다음 단계

• 속도 제한: 인증된 요청은 GitHub REST API에서 시간당 5,000회를 받을 수 있으며, 대화형 사용에 충분합니다.

• 나중에 쓰기 권한(이슈 열기, PR에 댓글 달기)이 필요하면 requests.post/patch를 사용하는 새 @mcp.tool() 함수를 추가하세요. 어떤 도구가 GitHub 상태를 변경하는지 명확히 보이도록 별도로 유지하고 이름을 명확하게 지정하세요.

• 이 서버를 claude.ai/Cowork에서도 사용하려면(Claude Code CLI/VS Code뿐만 아니라) stdio 전송에서 OAuth가 있는 호스팅 HTTP 서버로 전환해야 합니다. 이는 상당히 큰 작업이므로, 그런 접근성이 필요할 때만 가치가 있습니다.