HyunjunGil/mcp-github-server

GitHub MCP Server

FastMCP를 사용한 완전한 GitHub 통합 MCP Server입니다. Claude, Cursor 등의 AI 에이전트에서 GitHub API를 쉽게 사용할 수 있도록 도와줍니다.

🌟 주요 기능

• 사용자 관리: GitHub 사용자 정보 조회, 리포지토리 목록 확인
• 리포지토리 관리: 리포지토리 생성, 정보 조회, 파일 목록 확인, 브랜치 생성
• 파일 관리: 파일 내용 조회, 생성, 수정, 삭제
• Pull Request: PR 생성 및 목록 조회
• 이슈 관리: 이슈 생성, 조회, 수정, 종료
• 이중 통신 지원: stdio 모드(Claude/Cursor용) + HTTP 모드(웹 API용)

🚀 빠른 시작

1. 의존성 설치

pip install -r requirements.txt

2. GitHub Personal Access Token 생성

1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. "Generate new token (classic)" 클릭
3. 필요한 권한 선택:
   • repo (전체 리포지토리 액세스)
   • read:user (사용자 정보 읽기)
4. 토큰 생성 및 복사

3. 환경변수 설정

# .env 파일 생성 (env.example을 참고)
cp env.example .env

# .env 파일 편집
GITHUB_TOKEN=your_github_token_here
LOG_LEVEL=INFO
HTTP_HOST=0.0.0.0
HTTP_PORT=8080

4. 서버 실행

stdio 모드 (Claude/Cursor용)

python run_stdio.py

HTTP 모드 (웹 API용)

python run_http.py

📋 사용 가능한 도구

사용자 관련

• get_user_info: 현재 사용자 정보 조회
• get_user_repos: 사용자 리포지토리 목록 조회

리포지토리 관련

• create_repository: 새 리포지토리 생성
• get_repository_info: 리포지토리 정보 조회
• list_repository_contents: 리포지토리 파일 목록 조회
• create_branch: 새 브랜치 생성

파일 관련

• get_file_content: 파일 내용 조회
• create_file: 새 파일 생성
• update_file: 기존 파일 수정
• delete_file: 파일 삭제

Pull Request 관련

• create_pull_request: 새 PR 생성
• list_pull_requests: PR 목록 조회

이슈 관련

• create_issue: 새 이슈 생성
• list_issues: 이슈 목록 조회
• update_issue: 이슈 수정
• close_issue: 이슈 닫기

🔧 Cursor/Claude 설정

Cursor MCP 설정

~/.cursor/mcp.json 파일에 다음 설정을 추가하세요:

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "python",
      "args": ["run_stdio.py"],
      "cwd": "/path/to/mcp-github-server"
    }
  }
}

중요: GitHub 토큰은 환경변수로 설정하세요:

# ~/.zshrc 또는 ~/.bashrc에 추가
export GITHUB_TOKEN="your_github_token_here"

# 또는 Cursor 실행 전에 환경변수 설정
export GITHUB_TOKEN="your_github_token_here"
/Applications/Cursor.app/Contents/MacOS/Cursor

📁 프로젝트 구조

mcp-github-server/
├── src/
│   └── github_mcp_server/
│       ├── __init__.py
│       ├── server.py            # FastMCP 서버 메인
│       ├── github_client.py     # GitHub API 클라이언트
│       ├── config.py            # 설정 관리
│       └── tools/               # MCP 도구들
│           ├── __init__.py
│           ├── user_tools.py    # 사용자 정보 조회
│           ├── repo_tools.py    # 리포지토리 관리
│           ├── file_tools.py    # 파일 수정
│           ├── pr_tools.py      # Pull Request 관리
│           └── issue_tools.py   # 이슈 관리
├── run_stdio.py                 # stdio 모드 실행
├── run_http.py                  # HTTP 모드 실행
├── requirements.txt
├── env.example                  # 환경변수 템플릿
├── .gitignore
└── README.md

🔐 보안 고려사항

• GitHub Personal Access Token을 안전하게 관리하세요
• .env 파일을 버전 관리에서 제외하세요 (이미 .gitignore에 포함됨)
• 필요한 최소한의 권한만 부여하세요
• 토큰에 만료일을 설정하는 것을 권장합니다

🛠️ 개발

개발 모드로 실행

# stdio 모드
python src/github_mcp_server/server.py

# HTTP 모드
python src/github_mcp_server/server.py --http

MCP 프로토콜 수동 초기화 테스트

서버 실행 후 JSON-RPC 2.0 호출로 직접 초기화:

# 1단계: 서버 실행
export GITHUB_TOKEN="your_github_token_here"
python run_stdio.py

서버가 실행되면 다음 JSON-RPC 호출들을 순서대로 입력:

// 1. 초기화 요청 (initialize)
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}

// 2. 초기화 완료 알림 (notifications/initialized)
{"jsonrpc": "2.0", "method": "notifications/initialized", "params": {}}

// 3. 도구 목록 조회 (tools/list)
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}

// 4. 사용자 정보 조회 테스트
{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "get_user_info", "arguments": {}}}

// 5. 리포지토리 목록 조회 테스트
{"jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": {"name": "get_user_repos", "arguments": {"per_page": 5}}}

중요: 각 JSON 요청 후 Enter를 두 번 눌러야 서버가 인식합니다.

📄 라이선스

MIT License

🤝 기여

Pull Request와 이슈 제출을 환영합니다!

📞 지원

문제가 있거나 질문이 있으시면 GitHub 이슈를 생성해 주세요.