Skip to main content
Glama

GitHub MCP Server

by HyunjunGil
OverviewInspectNewSchemaRelated ServersScore
Python
Remote
  • Apple

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 생성

  1. GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)

  2. Generate new token 클릭

  3. 필요한 권한 선택:

    • repo (전체 리포지토리 액세스)

  4. 생성된 토큰 복사

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 클라이언트에서 이 서버에 연결하려면:

  1. 서버 시작:

    python -m github_mcp_server

  2. 연결 설정:

    # 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" }

🔧 에러 처리

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

  1. HTTP 에러: GitHub API rate limit, 인증 실패 등

  2. 권한 에러: 토큰 권한 부족

  3. 데이터 검증 에러: 잘못된 매개변수

  4. 네트워크 에러: 연결 실패, 타임아웃

📊 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/

🔨 새로운 도구 추가하기

  1. 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)}")

  2. 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)

🔐 보안 고려사항

  1. 토큰 관리:

    • 환경변수 또는 비밀 관리 서비스 사용

    • 토큰 로테이션 주기적 수행

    • 최소 권한 원칙 적용

  2. 네트워크 보안:

    • HTTPS 통신 강제

    • IP 화이트리스트 적용 (필요시)

    • VPN 또는 프라이빗 네트워크 사용

  3. 입력 검증:

    • 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

🤝 기여

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

📚 추가 리소스

🔗 관련 문서

📖 예시 프로젝트

🎯 사용 사례

  1. 자동화된 릴리즈: PR 머지 시 자동 태그 및 릴리즈 생성

  2. 이슈 관리: 템플릿 기반 이슈 생성 및 라벨링

  3. 코드 리뷰: 자동 리뷰어 할당 및 체크리스트 생성

  4. 프로젝트 관리: 마일스톤 기반 작업 추적

📞 지원 및 커뮤니티

🐛 이슈 신고

💡 기능 요청

🤝 기여 가이드

  1. Fork 후 feature 브랜치 생성

  2. 코드 작성 및 테스트 추가

  3. PR 생성 (템플릿 사용)

  4. 코드 리뷰 및 피드백 반영

💬 커뮤니티

⚠️ 주의사항:

  • 보안: 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 tested
-
quality - not tested

How are these scores calculated?

Related Resources

Appeared in Searches

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/HyunjunGil/custom-github-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server