GitHub GraphQL API MCP

GitHub GraphQL API를 쿼리하고 사용하기 위한 MCP(Model Control Protocol) 기반 도구입니다. 이 프로젝트는 GitHub GraphQL 스키마를 탐색하고 MCP 클라이언트 도구(예: Claude AI)를 통해 GraphQL 쿼리를 실행할 수 있는 서버를 제공합니다.

GitHub GraphQL API를 사용하는 이유

GitHub GraphQL API는 기존 REST API에 비해 다음과 같은 상당한 이점을 제공합니다.

정확한 데이터 검색 : GraphQL을 사용하면 클라이언트가 필요한 필드를 정확하게 지정하여 과도한 데이터를 피할 수 있습니다.
토큰 소모 감소 : 필요한 필드만 요청함으로써 API 응답 크기가 크게 줄어들어 AI 모델 토큰 소모가 감소합니다.
관련 데이터에 대한 단일 요청 : 하나의 쿼리로 여러 관련 리소스를 검색할 수 있으므로 요청 수가 줄어듭니다.
자체 문서화 : 내장된 문서화 시스템을 통해 외부 문서 없이 API 스키마를 직접 쿼리하고 이해할 수 있습니다.
강력한 유형 시스템 : 유형 검사를 제공하여 오류를 줄입니다.

이 프로젝트는 이러한 장점을 활용하여 GitHub GraphQL API 스키마를 효과적으로 탐색하고 최적화된 쿼리를 실행하는 데 도움이 되는 도구를 제공하고, AI 어시스턴트에게 효율적인 GitHub 데이터 검색 기능을 제공합니다.

응용 프로그램 시나리오

기본 기능

이 도구는 다음과 같은 일반적인 작업을 쉽게 구현합니다.

저장소 기본 정보 쿼리 : 저장소 이름, 설명, 별점 수, 브랜치 목록 및 기타 기본 정보를 가져옵니다.
이슈 데이터 검색 : 특정 저장소에 대한 이슈 목록, 세부 정보 또는 코멘트 콘텐츠 쿼리
사용자 프로필 액세스 : 사용자의 개인 프로필, 기여 통계 및 기타 공개 정보를 검색합니다.
풀 리퀘스트 상태 보기 : PR 기본 상태, 댓글 내용 및 병합 정보 가져오기
프로젝트 종속성 쿼리 : 프로젝트 종속성 패키지 목록 및 버전 정보 검색

탐색적 고급 기능

GraphQL의 유연한 쿼리 기능을 사용하면 다음과 같은 고급 분석 기능을 구현해 볼 수도 있습니다.

저장소 기여 추세 분석 : 커밋 데이터를 집계하고 프로젝트 활동을 평가하여 코드 업데이트 빈도와 기여자 참여를 분석합니다.
이슈 관리 및 분류 : 사용자 정의 조건에 따라 이슈 데이터를 정리하고, 우선순위 처리가 필요한 이슈를 발굴하여 프로젝트 관리 효율성을 향상시킵니다.
코드 검토 패턴 분석 : PR 의견 및 검토 프로세스를 분석하고, 일반적인 문제 패턴을 식별하고, 코드 검토 워크플로를 최적화합니다.
기여자 네트워크 시각화 : 프로젝트 기여자 간 협업 관계 구축, 주요 기여자 및 전문 분야 발견
종속성 상태 평가 : 프로젝트 종속성의 업데이트 빈도와 잠재적인 보안 문제를 평가하고 종속성 관리 제안을 제공합니다.

특징

GitHub GraphQL 스키마 루트 유형 쿼리(쿼리/변이)
특정 유형에 대한 자세한 문서를 받으세요
특정 필드에 대한 쿼리 문서 및 매개변수
GitHub GraphQL API 쿼리를 직접 실행하여 필요한 데이터를 정확하게 검색하고 토큰 소모를 줄입니다.
이중 언어 지원(영어/중국어)

필수 조건

Python 3.10 이상
GitHub 개인 액세스 토큰(GitHub API에 액세스하기 위한)
Poetry(추천 종속성 관리 도구)

설치

저장소를 복제합니다.

지엑스피1

Poetry를 사용하여 종속성을 설치합니다.

# If you haven't installed Poetry yet, install it first:
# curl -sSL https://install.python-poetry.org | python3 -

# Install dependencies using Poetry
poetry install

# Activate the virtual environment
poetry shell

시를 사용하지 않는다면 전통적인 방법을 사용할 수 있습니다.

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/MacOS
# or
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .

환경 변수 구성:

.env 파일을 만들고 GitHub 개인 액세스 토큰을 추가하세요.

GITHUB_TOKEN="your_github_token_here"

.env.example 파일을 복사하여 만들 수 있습니다.

cp .env.example .env

그런 다음 .env 파일을 편집하여 your_github_token_here 실제 GitHub 토큰으로 바꿉니다.

용법

서버 시작

Poetry 가상 환경( poetry shell )을 활성화했는지 확인하세요. 그런 다음:

달리다

python github_graphql_api_mcp_server.py

서버가 시작된 후 MCP 클라이언트(예: Claude AI)를 통해 서버에 연결할 수 있습니다.

Claude Desktop에서 구성

Claude 데스크톱 앱에서 이 MCP 서버를 구성하여 원클릭 시작이 가능합니다.

Claude 데스크톱 앱을 엽니다
설정으로 이동하여 MCP 서버 구성 섹션을 찾으세요.
다음 구성을 추가합니다(실제 경로에 맞게 수정):

{
    "mcpServers": {
        "github_mcp": {
            "command": "<your Python interpreter path>",
            "args": [
                "--directory",
                "<project path>",
                "run",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

구성 예:

{
    "mcpServers": {
        "github_mcp": {
            "command": "/usr/bin/python3",
            "args": [
                "--directory",
                "/home/user/projects/github_graphql_api_mcp/",
                "run",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

conda 또는 다른 환경 관리 도구를 사용하는 경우:

{
    "mcpServers": {
        "github_mcp": {
            "command": "/opt/miniconda3/bin/python",
            "args": [
                "--directory",
                "/Users/username/github/github_graphql_api_mcp/",
                "run",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

구성 후, 수동으로 시작하지 않고도 Claude 데스크톱 앱에서 직접 MCP 서버를 시작할 수 있습니다.

사용 가능한 도구

서버는 다음과 같은 도구를 제공합니다.

print_type_field : GitHub GraphQL 스키마 루트 유형의 쿼리 필드
graphql_schema_root_type : 루트 유형(쿼리/변이)에 대한 설명서를 가져옵니다.
graphql_schema_type : 특정 유형에 대한 쿼리 문서
call_github_graphql : GitHub GraphQL API 쿼리 실행

사용 예

MCP 클라이언트를 사용하여 서버에 연결한 후 다음을 수행할 수 있습니다.

쿼리 루트 유형 설명서:
Use the graphql_schema_root_type tool, parameter type_name="QUERY"
특정 유형의 쿼리 필드:
Use the print_type_field tool, parameters type_name="QUERY", type_fields_name="repository"
특정 유형에 대한 쿼리 문서:
Use the graphql_schema_type tool, parameter type_name="Repository"
GraphQL 쿼리를 실행합니다.
Use the call_github_graphql tool, parameter: graphql=""" query { viewer { login name } } """

스크린샷 예시

다음은 Claude와 함께 GitHub GraphQL API MCP를 사용하는 예입니다.

노트

사용하기 전에 GitHub 토큰에 적절한 권한이 있는지 확인하세요.
토큰은 버전 제어 시스템에 커밋되어서는 안 되는 .env 파일에 저장됩니다.
쿼리는 GitHub API 사용 제한을 준수해야 합니다.

특허

자세한 내용은 MIT 라이선스를 참조하세요.

GitHub GraphQL API MCP

Integrations