GitHub GraphQL API를 쿼리하고 사용하기 위한 MCP(Model Control Protocol) 기반 도구입니다. 이 프로젝트는 GitHub GraphQL 스키마를 탐색하고 MCP 클라이언트 도구(예: Claude AI)를 통해 GraphQL 쿼리를 실행할 수 있는 서버를 제공합니다.
GitHub GraphQL API는 기존 REST API에 비해 다음과 같은 상당한 이점을 제공합니다.
정확한 데이터 검색 : GraphQL을 사용하면 클라이언트가 필요한 필드를 정확하게 지정하여 과도한 데이터를 피할 수 있습니다.
토큰 소모 감소 : 필요한 필드만 요청함으로써 API 응답 크기가 크게 줄어들어 AI 모델 토큰 소모가 감소합니다.
관련 데이터에 대한 단일 요청 : 하나의 쿼리로 여러 관련 리소스를 검색할 수 있으므로 요청 수가 줄어듭니다.
자체 문서화 : 내장된 문서화 시스템을 통해 외부 문서 없이 API 스키마를 직접 쿼리하고 이해할 수 있습니다.
강력한 유형 시스템 : 유형 검사를 제공하여 오류를 줄입니다.
이 프로젝트는 이러한 장점을 활용하여 GitHub GraphQL API 스키마를 효과적으로 탐색하고 최적화된 쿼리를 실행하는 데 도움이 되는 도구를 제공하고, AI 어시스턴트에게 효율적인 GitHub 데이터 검색 기능을 제공합니다.
Related MCP server: @cloud9-labs/mcp-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 데스크톱 앱에서 이 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 라이선스에 따라 라이선스가 부여되었습니다. 이는 사용자가 저작권 고지와 라이선스 설명을 보존하는 한 소프트웨어를 자유롭게 사용, 수정, 배포 및 상용화할 수 있는 매우 관대한 라이선스입니다.
자세한 내용은 MIT 라이선스를 참조하세요.
A tool to execute GitHub GraphQL API queries. Before using, it's recommended to check the documentation first, and include ID fields in your queries for easier follow-up operations Args: graphql: The GraphQL query Returns: str: Execution result
| Name | Required | Description | Default |
|---|---|---|---|
| graphql | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions checking documentation and including ID fields, which adds some operational context, but fails to address critical traits like authentication requirements, rate limits, error handling, or mutation vs. query behavior. For a GraphQL API tool with zero annotation coverage, this leaves significant gaps in understanding how the tool behaves in practice.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and usage recommendation in the first sentence. The Args and Returns sections are structured but could be more integrated. There's minimal waste, though the 'Returns: str: Execution result' is redundant given the output schema, slightly reducing efficiency.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (GraphQL API execution) and the presence of an output schema (which handles return values), the description is partially complete. It covers basic purpose and some usage tips but lacks details on authentication, error cases, or integration with sibling tools. Without annotations and with low schema coverage, it doesn't fully equip an agent for reliable tool invocation in a GitHub context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal meaning beyond the input schema: it names the single parameter 'graphql' and states it's 'The GraphQL query', which the schema already indicates as a string type. With 0% schema description coverage, the description doesn't compensate by explaining query syntax, validation rules, or examples. The baseline is 3 because the schema covers the parameter's existence and type, but the description fails to enhance understanding significantly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'execute GitHub GraphQL API queries' with a specific verb (execute) and resource (GitHub GraphQL API queries). It distinguishes itself from sibling tools like graphql_schema_root_type and graphql_schema_type by focusing on query execution rather than schema exploration. However, it doesn't explicitly contrast with print_type_field, leaving some sibling differentiation incomplete.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implied usage guidance by recommending checking documentation first and including ID fields for follow-up operations, which suggests context for when to use this tool effectively. However, it lacks explicit when/when-not criteria or named alternatives to sibling tools, leaving the agent to infer optimal usage scenarios without clear boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A tool to query GitHub GraphQL schema root types. You need to provide the root type name (QUERY/MUTATION) Args: type_name: root type (QUERY or MUTATION) Returns: str: Documentation content
| Name | Required | Description | Default |
|---|---|---|---|
| type_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral context. It states the tool returns documentation content as a string but doesn't disclose authentication requirements, rate limits, error handling, or what specific documentation format to expect. The 'query' verb implies read-only, but this isn't explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized with three sentences: purpose statement, parameter guidance, and return value. It's front-loaded with the core function. Minor improvements could include bullet points for Args/Returns, but overall it's efficient with minimal waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no annotations, no output schema, and low schema coverage, the description is incomplete. It lacks details on authentication, error cases, the structure of returned documentation, or how this integrates with sibling tools. The return type 'str: Documentation content' is vague without examples or format specifications.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description compensates by explaining that 'type_name' should be 'QUERY or MUTATION' and represents the 'root type name.' This adds meaningful context beyond the schema's generic 'Type Name' title, though it doesn't detail format constraints or examples.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'query GitHub GraphQL schema root types' with specific resource (GitHub GraphQL schema) and verb (query). It distinguishes from sibling 'graphql_schema_type' by focusing on root types only, though it doesn't explicitly contrast with 'call_github_graphql' or 'print_type_field'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like 'graphql_schema_type' for non-root types or 'call_github_graphql' for actual queries. The description mentions needing to provide root type name but doesn't explain use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A tool to query specific type documentation in GitHub GraphQL schema. You need to provide the type_name
Args:
type_name: Type name like SecurityAdvisoryConnection
Returns:
str: Documentation content
| Name | Required | Description | Default |
|---|---|---|---|
| type_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool queries documentation, implying a read-only operation, but doesn't specify if it's safe, requires authentication, has rate limits, or what happens on errors. For a query tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the purpose clearly. The 'Args:' and 'Returns:' sections are structured but slightly redundant with the schema. It's concise with no wasted words, though the formatting could be more integrated.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (1 parameter, no output schema, no annotations), the description is somewhat complete but has gaps. It covers the basic purpose and parameter semantics but lacks usage guidelines, behavioral details, and output explanation. For a simple query tool, it's adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It explains the single parameter 'type_name' as 'Type name like `SecurityAdvisoryConnection`,' adding meaning beyond the schema's basic 'string' type. This clarifies the parameter's purpose and provides an example, though it could be more detailed about valid type names or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'query specific type documentation in GitHub GraphQL schema.' It specifies the verb ('query'), resource ('type documentation'), and domain ('GitHub GraphQL schema'). However, it doesn't explicitly differentiate from sibling tools like 'graphql_schema_root_type' or 'print_type_field' beyond mentioning 'specific type' documentation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides minimal guidance: 'You need to provide the type_name' and gives an example ('SecurityAdvisoryConnection'). It doesn't explain when to use this tool versus alternatives like 'graphql_schema_root_type' or 'print_type_field,' nor does it mention prerequisites or exclusions. The guidance is basic and lacks context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
A tool to query GitHub GraphQL schema root type fields. You need to provide root_type_name and type_fields_name
Args:
type_name: root type like QUERY or MUTATION
type_fields_name: field name like repository based on root type documentation
Returns:
str: Documentation content for the specified field
| Name | Required | Description | Default |
|---|---|---|---|
| type_name | Yes | ||
| type_fields_name | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that the tool returns documentation content as a string, which is useful behavioral information. However, it doesn't mention whether this is a read-only operation, what happens with invalid inputs, if there are rate limits, authentication requirements, or error behavior. For a query tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is reasonably concise but has structural issues. The first sentence clearly states the purpose, but the parameter explanations are formatted as 'Args:' and 'Returns:' sections which are somewhat redundant with the schema. The information is front-loaded but could be more efficiently integrated. It's not excessively verbose but has minor organizational inefficiencies.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 2 parameters with 0% schema coverage and no output schema, the description provides adequate parameter semantics and specifies the return type as a string. However, it doesn't explain the format of the returned documentation content, error conditions, or authentication requirements. For a query tool with no annotations, this is minimally complete but lacks depth about operational behavior and integration context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides meaningful semantics for both parameters: 'type_name' is explained as 'root type like `QUERY` or `MUTATION`' and 'type_fields_name' as 'field name like `repository` based on root type documentation'. This adds substantial value beyond the bare schema, though it doesn't provide exhaustive examples or format details. With 2 parameters fully addressed, this exceeds the baseline expectation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'query GitHub GraphQL schema root type fields' with specific verbs ('query') and resources ('GitHub GraphQL schema root type fields'). It distinguishes from siblings like 'call_github_graphql' (which executes queries) and 'graphql_schema_type' (which might query non-root types), but doesn't explicitly contrast them. The purpose is specific but sibling differentiation is implied rather than explicit.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions 'based on root type documentation' but doesn't specify when this tool is appropriate compared to sibling tools like 'graphql_schema_root_type' or 'graphql_schema_type'. There are no explicit when/when-not instructions or named alternatives, leaving usage context unclear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
call_github_graphqlgraphql_schema_root_typegraphql_schema_typeprint_type_fieldScored across 4 tools
The tools have overlapping purposes focused on GitHub GraphQL schema exploration, which could cause confusion. call_github_graphql is distinct for executing queries, but graphql_schema_root_type, graphql_schema_type, and print_type_field all retrieve schema documentation with subtle differences in scope (root types vs. specific types vs. root type fields). Descriptions help clarify, but an agent might struggle to choose between them for schema inspection tasks.
Tool names follow a consistent snake_case pattern with clear verb_noun structure (e.g., call_github_graphql, graphql_schema_type). Minor deviations exist, such as graphql_schema_root_type using 'root_type' while print_type_field uses 'type_field', but overall the naming is predictable and readable across all tools.
With 4 tools, the count is reasonable for a GitHub GraphQL API server, providing a focused set for query execution and schema exploration. It's slightly thin for comprehensive API coverage but well-scoped for its intended purpose, avoiding bloat while supporting core workflows like querying and schema lookup.
The tool set covers query execution and schema documentation retrieval, but has notable gaps for a GitHub API surface. It lacks CRUD operations for resources like repositories, issues, or pull requests, and doesn't support mutations or advanced query building. Agents can work around this by crafting GraphQL queries, but the surface is incomplete for typical GitHub automation tasks.
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
Repository knowledge graph MCP server for codebase understanding and debugging.
An MCP server that gives your AI access to the source code and docs of all public github repos
The Cortex MCP server provides read-only access to real-time engineering context from the Cortex developer portal, allowing AI coding assistants to answer natural language questions about your organization's catalog (microservices, libraries, domains, teams, infrastructure), scorecards (engineering standards and best practices), initiatives (goals and deadlines), and Engineering Intelligence metrics. It includes tools for querying documentation, tracking personal entities, and accessing AI-assisted insights across the entire Cortex ecosystem.
