GitHub MCP Server

GitHub MCP Server (FastMCP)

GitHub API를 활용한 Model Context Protocol (MCP) 서버입니다. Claude Desktop, Cursor, 또는 다른 MCP 클라이언트에서 GitHub 작업을 직접 수행할 수 있도록 포괄적인 도구를 제공합니다.

🌟 특징

완전한 GitHub API 통합: 리포지토리, 브랜치, 이슈, PR, 파일 관리 등 주요 GitHub 기능을 모두 지원
FastMCP 기반: 최신 MCP 프로토콜을 사용한 고성능 서버
PyGithub 활용: 안정적이고 검증된 GitHub API 클라이언트 라이브러리 사용
상세한 에러 처리: 명확한 에러 메시지와 로깅
타입 안전성: Pydantic 모델을 통한 데이터 검증
확장 가능한 구조: 새로운 GitHub API 기능을 쉽게 추가할 수 있는 모듈화된 설계

🚀 주요 기능

📁 Repository 관리

✅ 새 리포지토리 생성: 공개/비공개 리포지토리 생성
✅ 리포지토리 조회: 특정 리포지토리 정보 확인
✅ 리포지토리 목록: 사용자의 모든 리포지토리 조회

🌿 Branch 관리

✅ 새 브랜치 생성: 기존 브랜치에서 새 브랜치 생성
✅ 브랜치 목록 조회: 리포지토리의 모든 브랜치 확인

🐛 Issue 관리

✅ 이슈 생성: 새 이슈 작성 (라벨, 담당자 지정 가능)
✅ 이슈 목록 조회: 열린/닫힌/모든 이슈 확인
✅ 특정 이슈 조회: 이슈 번호로 상세 정보 확인

🔀 Pull Request 관리

✅ PR 생성: 새 Pull Request 생성 (Draft PR 지원)
✅ PR 목록 조회: 열린/닫힌/모든 PR 확인
✅ 특정 PR 조회: PR 번호로 상세 정보 확인

📝 파일 관리

✅ 파일 생성: 새 파일 생성 및 커밋
✅ 파일 수정: 기존 파일 업데이트
✅ 파일 조회: 파일 내용 및 메타데이터 확인

📝 커밋 관리

✅ 커밋 목록 조회: 리포지토리 또는 특정 브랜치의 커밋 히스토리

👤 사용자 정보

✅ 사용자 프로필 조회: GitHub 사용자 정보 확인

📋 요구사항

Python 3.8+
GitHub Personal Access Token
Claude Desktop 또는 Cursor (연동용)

🛠️ 설치 및 설정

1. 프로젝트 복제 및 설치

# 의존성 설치
pip install -r requirements.txt

# 개발모드로 패키지 설치
pip install -e .

2. GitHub Token 생성

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
Generate new token 클릭
필요한 권한 선택:
- repo (전체 리포지토리 액세스)
생성된 토큰 복사

3. 환경변수 설정

# env.example을 .env로 복사
cp env.example .env

# .env 파일 편집
GITHUB_TOKEN=your_github_token_here

4. 서버 테스트

# 직접 실행
python -m github_mcp_server

# 또는 설치된 명령어 사용
github-mcp-server

🔗 Claude Desktop 연동

1. Claude Desktop 설정 파일 위치

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\\Claude\\claude_desktop_config.json

2. 설정 파일 수정

{
  "mcpServers": {
    "github-mcp-server": {
      "command": "python",
      "args": ["-m", "github_mcp_server"],
      "cwd": "/path/to/your/github-mcp-server",
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

3. Claude Desktop 재시작

설정 변경 후 Claude Desktop을 완전히 종료하고 다시 시작하세요.

📖 사용 방법

Claude Desktop에서 다음과 같이 요청할 수 있습니다:

📁 Repository 관리

"GitHub에 새 리포지토리를 만들어주세요"
- 이름: my-awesome-project
- 설명: 새로운 프로젝트입니다
- 공개 리포지토리로 설정

"내 GitHub 리포지토리 목록을 보여주세요"

"facebook/react 리포지토리 정보를 알려주세요"

🌿 Branch 관리

"새 브랜치를 만들어주세요"
- 리포지토리: username/my-repo
- 브랜치 이름: feature/new-feature
- 기준 브랜치: main

"username/my-repo의 모든 브랜치를 보여주세요"

🐛 Issue 관리

"이슈를 만들어주세요"
- 리포지토리: username/my-repo
- 제목: 버그 수정 필요
- 내용: 상세한 버그 내용...

"username/my-repo의 열린 이슈 목록을 보여주세요"

"username/my-repo의 이슈 #42 상세 정보를 알려주세요"

🔀 Pull Request 관리

"풀 리퀘스트를 만들어주세요"
- 리포지토리: username/my-repo
- 제목: 새 기능 추가
- 소스 브랜치: feature/new-feature
- 타겟 브랜치: main

"username/my-repo의 모든 PR을 보여주세요"

"username/my-repo의 PR #15 정보를 알려주세요"

📝 커밋 및 사용자 정보

"username/my-repo의 최근 커밋들을 보여주세요"

"facebook 사용자 정보를 알려주세요"

"내 GitHub 프로필 정보를 보여주세요"

🏗️ 아키텍처 및 구조

📁 프로젝트 구조

src/github_mcp_server/
├── __init__.py           # 패키지 초기화
├── __main__.py           # CLI 진입점 및 서버 시작
├── server.py             # FastMCP 서버 및 도구 정의
└── github_client.py      # GitHub API 클라이언트 (PyGithub 래퍼)

🔗 주요 구성요소

1. GitHubClient (`github_client.py`)

역할: GitHub API와의 실제 통신 담당
기술: PyGithub 라이브러리 기반
데이터 모델: Pydantic 모델을 통한 타입 안전성 보장
에러 처리: 상세한 로깅 및 예외 처리

2. FastMCP Server (`server.py`)

역할: MCP 프로토콜 구현 및 도구 노출
기술: FastMCP 프레임워크 사용
도구 등록: @mcp.tool 데코레이터를 통한 자동 도구 등록
응답 형식: 일관된 JSON 응답 구조

3. CLI Interface (`main.py`)

역할: 명령줄 인터페이스 및 서버 초기화
환경 설정: .env 파일 로드 및 환경변수 검증
로깅 설정: 파일 및 콘솔 로깅 구성

📦 데이터 모델

# 주요 Pydantic 모델들
class GitHubRepository(BaseModel):
    name: str
    full_name: str
    description: Optional[str]
    html_url: str
    private: bool
    default_branch: str

class GitHubBranch(BaseModel):
    name: str
    sha: str
    url: str

class GitHubIssue(BaseModel):
    number: int
    title: str
    body: Optional[str]
    state: str
    html_url: str
    user: Dict[str, Any]

class GitHubFile(BaseModel):
    name: str
    path: str
    sha: str
    size: int
    content: Optional[str]
    # ... 기타 필드들

🛠️ MCP 도구 API 레퍼런스

📁 Repository 관리

도구 이름	설명	필수 매개변수	선택 매개변수
`create_repository`	새 리포지토리 생성	`name`	`description`, `private`, `auto_init`
`list_repositories`	리포지토리 목록 조회	없음	`per_page`

🌿 Branch 관리

도구 이름	설명	필수 매개변수	선택 매개변수
`create_branch`	새 브랜치 생성	`owner`, `repo`, `branch_name`	`from_branch`
`list_branches`	브랜치 목록 조회	`owner`, `repo`	`per_page`

📝 파일 관리

도구 이름	설명	필수 매개변수	선택 매개변수
`create_file`	새 파일 생성	`owner`, `repo`, `path`, `content`, `message`	`branch`, `author_name`, `author_email`
`update_file`	파일 수정	`owner`, `repo`, `path`, `content`, `message`, `sha`	`branch`, `author_name`, `author_email`
`get_file`	파일 조회	`owner`, `repo`, `path`	`ref`

🐛 Issue 관리

도구 이름	설명	필수 매개변수	선택 매개변수
`create_issue`	새 이슈 생성	`owner`, `repo`, `title`	`body`, `labels`, `assignees`
`get_issue`	특정 이슈 조회	`owner`, `repo`, `issue_number`	없음
`list_issues`	이슈 목록 조회	`owner`, `repo`	`state`, `per_page`

🔀 Pull Request 관리

도구 이름	설명	필수 매개변수	선택 매개변수
`create_pull_request`	새 PR 생성	`owner`, `repo`, `title`, `head`	`base`, `body`, `draft`
`get_pull_request`	특정 PR 조회	`owner`, `repo`, `pr_number`	없음
`list_pull_requests`	PR 목록 조회	`owner`, `repo`	`state`, `per_page`

📝 커밋 관리

도구 이름	설명	필수 매개변수	선택 매개변수
`list_commits`	커밋 목록 조회	`owner`, `repo`	`branch`, `per_page`

👤 사용자 정보

도구 이름	설명	필수 매개변수	선택 매개변수
`get_user_info`	사용자 정보 조회	없음	`username`

🔌 MCP Client 개발 가이드

🚀 빠른 시작

MCP 클라이언트에서 이 서버에 연결하려면:

서버 시작:
python -m github_mcp_server
연결 설정:
# MCP 클라이언트 코드 예시 import asyncio from mcp import ClientSession, StdioServerParameters async def main(): server_params = StdioServerParameters( command="python", args=["-m", "github_mcp_server"], env={"GITHUB_TOKEN": "your_token_here"} ) async with ClientSession(server_params) as (read, write): # 도구 사용 예시 result = await session.call_tool("list_repositories", {}) print(result)

📋 응답 형식

모든 도구는 일관된 JSON 응답 형식을 반환합니다:

{
  "success": true|false,
  "message": "사용자 친화적 메시지",
  "data": { /* 실제 데이터 */ },
  "error": "에러 메시지 (실패시만)"
}

성공 응답 예시:

{
  "success": true,
  "message": "✅ 리포지토리 'my-repo' 생성 완료!",
  "repository": {
    "name": "my-repo",
    "full_name": "username/my-repo",
    "url": "https://github.com/username/my-repo",
    "private": false,
    "default_branch": "main"
  }
}

실패 응답 예시:

{
  "success": false,
  "message": "❌ 리포지토리 생성 실패: Repository already exists",
  "error": "Repository already exists"
}

🔧 에러 처리

클라이언트에서 에러를 처리할 때 고려사항:

HTTP 에러: GitHub API rate limit, 인증 실패 등
권한 에러: 토큰 권한 부족
데이터 검증 에러: 잘못된 매개변수
네트워크 에러: 연결 실패, 타임아웃

📊 Rate Limiting

GitHub API의 rate limit을 고려해야 합니다:

인증된 요청: 시간당 5,000회
비인증 요청: 시간당 60회

클라이언트에서 다음을 구현하는 것을 권장합니다:

Rate limit 헤더 모니터링
적절한 재시도 로직
요청 간격 조절

🐛 문제 해결

서버가 시작되지 않는 경우

github_mcp_server.log 파일 확인
GitHub token이 올바른지 확인
Python 경로가 올바른지 확인

Claude에서 도구가 보이지 않는 경우

Claude Desktop 완전 재시작
설정 파일 경로 확인
JSON 문법 오류 확인

GitHub API 오류

Token 권한 확인 (repo 스코프 필요)
Rate limit 확인 (시간당 5000회)
네트워크 연결 확인

📝 로그 확인

서버 로그는 github_mcp_server.log 파일에 저장됩니다:

# 실시간 로그 확인
tail -f github_mcp_server.log

# 최근 로그 확인
tail -n 50 github_mcp_server.log

🔧 개발 및 확장

개발 환경 설정

# 개발 의존성 설치
pip install -e ".[dev]"

# 코드 포맷팅
black src/

# 린트 검사
flake8 src/

# 타입 검사
mypy src/

🔨 새로운 도구 추가하기

GitHubClient에 메서드 추가 (github_client.py):
def my_new_feature(self, param1: str, param2: int) -> MyModel: """새로운 GitHub 기능 구현""" try: # PyGithub API 호출 result = self.github.some_api_call(param1, param2) return self._convert_to_model(result) except Exception as e: logger.error(f"기능 실행 실패: {str(e)}") raise Exception(f"기능 실행 실패: {str(e)}")
MCP 도구로 등록 (server.py):
@mcp.tool def my_new_feature(param1: str, param2: int) -> Dict[str, Any]: """새로운 GitHub 기능을 위한 MCP 도구""" if not github_client: raise Exception("GitHub 클라이언트가 초기화되지 않았습니다.") try: result = github_client.my_new_feature(param1, param2) return { "success": True, "message": f"✅ 기능 실행 완료!", "data": result.dict() } except Exception as e: return { "success": False, "message": f"❌ 기능 실행 실패: {str(e)}", "error": str(e) }

🔍 로깅 및 디버깅

로그 레벨 설정: LOG_LEVEL 환경변수 (DEBUG, INFO, WARNING, ERROR)
로그 파일: github_mcp_server.log
실시간 로그 모니터링: tail -f github_mcp_server.log

🧪 테스트 가이드

# 단위 테스트 실행
pytest tests/

# 통합 테스트 (실제 GitHub API 사용)
pytest tests/integration/ --github-token=your_token

# 커버리지 리포트
pytest --cov=github_mcp_server --cov-report=html

# 특정 도구 테스트
pytest tests/test_tools.py::test_create_repository

📊 성능 모니터링

Rate Limit 모니터링: GitHub API 응답 헤더 추적
응답 시간 측정: 각 도구의 실행 시간 로깅
메모리 사용량: 대용량 리포지토리 작업 시 모니터링

🚀 배포 및 운영

🐳 Docker 배포

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install -r requirements.txt

COPY src/ src/
RUN pip install -e .

ENV GITHUB_TOKEN=""
CMD ["python", "-m", "github_mcp_server"]

☁️ 클라우드 배포

AWS Lambda

# lambda_handler.py
import asyncio
from github_mcp_server.server import mcp

def lambda_handler(event, context):
    # MCP over HTTP 구현
    return asyncio.run(handle_mcp_request(event))

Google Cloud Functions

# main.py
from flask import Flask, request
from github_mcp_server.server import mcp

app = Flask(__name__)

@app.route('/mcp', methods=['POST'])
def handle_mcp():
    # MCP over HTTP 구현
    return process_mcp_request(request.json)

🔐 보안 고려사항

토큰 관리:
- 환경변수 또는 비밀 관리 서비스 사용
- 토큰 로테이션 주기적 수행
- 최소 권한 원칙 적용
네트워크 보안:
- HTTPS 통신 강제
- IP 화이트리스트 적용 (필요시)
- VPN 또는 프라이빗 네트워크 사용
입력 검증:
- Pydantic을 통한 데이터 검증
- SQL Injection 등 보안 취약점 방지
- 파일 경로 검증

📈 모니터링 및 알림

# monitoring.py
import logging
from prometheus_client import Counter, Histogram, start_http_server

# 메트릭 정의
api_calls_total = Counter('github_api_calls_total', 'Total GitHub API calls', ['method', 'status'])
api_duration = Histogram('github_api_duration_seconds', 'GitHub API call duration')

# 사용 예시
@api_duration.time()
def timed_api_call():
    # GitHub API 호출
    api_calls_total.labels(method='GET', status='success').inc()

🔄 CI/CD 파이프라인

# .github/workflows/ci.yml
name: CI/CD Pipeline

on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install dependencies
        run: |
          pip install -r requirements.txt
          pip install -e .
      
      - name: Run tests
        run: pytest
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      
      - name: Deploy to production
        if: github.ref == 'refs/heads/main'
        run: |
          # 배포 스크립트 실행
          ./deploy.sh

📄 라이선스

MIT License

🤝 기여

이슈와 풀 리퀘스트를 환영합니다!

📚 추가 리소스

🔗 관련 문서

📖 예시 프로젝트

🎯 사용 사례

자동화된 릴리즈: PR 머지 시 자동 태그 및 릴리즈 생성
이슈 관리: 템플릿 기반 이슈 생성 및 라벨링
코드 리뷰: 자동 리뷰어 할당 및 체크리스트 생성
프로젝트 관리: 마일스톤 기반 작업 추적

📞 지원 및 커뮤니티

🐛 이슈 신고

GitHub Issues
버그 리포트 템플릿 사용 권장

💡 기능 요청

Feature Request
사용 사례와 구체적인 요구사항 포함

🤝 기여 가이드

Fork 후 feature 브랜치 생성
코드 작성 및 테스트 추가
PR 생성 (템플릿 사용)
코드 리뷰 및 피드백 반영

💬 커뮤니티

⚠️ 주의사항:

보안: GitHub Personal Access Token을 안전하게 보관하세요
권한: 필요한 최소 권한만 부여하세요 (principle of least privilege)
Rate Limit: GitHub API 사용량을 모니터링하세요 (시간당 5,000회)
데이터: 민감한 정보가 로그에 기록되지 않도록 주의하세요
버전: 정기적으로 의존성을 업데이트하세요

🚀 성능 팁:

대량 작업 시 배치 처리 사용
캐싱을 통한 중복 API 호출 방지
비동기 처리로 응답 시간 개선
Rate limit에 도달하기 전 미리 대기

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables direct GitHub operations through Claude and Cursor, including repository management, branch creation, issue tracking, and pull request management. Provides seamless integration with GitHub API for comprehensive project workflow automation.