GitHub GraphQL API MCP

GitHub GraphQL API MCP

English | 中文 | 日本語 | Español | Français

这是一个基于 MCP（Model Context Protocol）的工具，用于查询和使用 GitHub GraphQL API。本项目提供了一个 MCP 服务，允许你通过 MCP 客户端工具（例如 Claude AI）探索 GitHub GraphQL 架构并执行 GraphQL 查询。

目录

• 为何使用 GitHub GraphQL API
• 应用场景
• 功能
• 与 GitHub 官方 MCP 服务的比较
• 前置条件
• 安装与使用
• 在 Claude Desktop 中配置
• 可用工具
• 使用示例
• 注意事项
• 许可证

为何使用 GitHub GraphQL API

与传统 REST API 相比，GitHub GraphQL API 具有显著优势：

• 精准获取数据：GraphQL 允许客户端明确指定所需字段，避免获取多余数据
• 减少 Token 消耗：只请求必要字段，可显著缩减 API 响应大小，降低 AI 模型的 Token 消耗
• 单次请求获取关联数据：一个查询即可获取多个关联资源，减少请求次数
• 自带文档：借助内置文档系统，你无需查阅外部文档，即可直接查询并了解 API 架构
• 强类型系统：提供类型检查，减少错误

本项目利用这些优势提供相应工具，帮助你有效探索 GitHub GraphQL API 架构并执行优化后的查询，为 AI 助手提供高效的 GitHub 数据获取能力。

应用场景

基础功能

此工具可以轻松实现以下常见操作：

1. 仓库基本信息查询：获取仓库名称、描述、星标数、分支列表及其他基本信息
2. Issue 数据获取：查询特定仓库的 Issue 列表、详情或评论内容
3. 用户资料访问：获取用户的个人资料、贡献统计及其他公开信息
4. Pull Request 状态查看：获取 PR 基本状态、评论内容和合并信息
5. 项目依赖查询：获取项目依赖包列表和版本信息

探索性高级功能

借助 GraphQL 灵活的查询能力，你还可以尝试实现以下高级分析功能：

1. 仓库贡献趋势分析：通过汇总提交数据，分析代码更新频率和贡献者参与情况，评估项目活跃度
2. Issue 管理与分类：根据自定义条件整理 Issue 数据，发现需要优先处理的问题，提升项目管理效率
3. 代码审查模式分析：分析 PR 评论和审查流程，识别常见问题模式并优化代码审查工作流
4. 贡献者网络可视化：构建项目贡献者之间的协作关系，发现关键贡献者及其专长领域
5. 依赖项健康评估：评估项目依赖项的更新频率和潜在安全问题，并提供依赖管理建议

功能

• 查询 GitHub GraphQL 架构的根类型（Query/Mutation）
• 获取特定类型的详细文档
• 查询特定字段的文档和参数
• 直接执行 GitHub GraphQL API 查询，精准获取所需数据并减少 Token 消耗
• 支持多种语言（英语/中文/日语/西班牙语/法语）

与官方 GitHub MCP 服务对比

与官方 github-mcp-server 相比，本项目在特定场景下具有独特优势：

功能	GitHub GraphQL API MCP	官方 GitHub MCP Server
核心机制	单次 GraphQL 查询	多个 REST API / 细粒度工具
数据检索	一次完成：通过单次请求获取仓库详情、议题、PR、历史记录和发布信息	分多步完成：需要依次调用 search_repositories、get_file_contents、list_commits 等工具
效率	高。最大限度减少网络延迟和往返次数。	复杂数据收集效率较低。由于工具需要依次调用，延迟较高。
Token 用量	已优化。仅返回请求的字段。	较高。中间工具输出（完整 JSON 响应）会占用上下文窗口。
灵活性	高。客户端可定义所需的确切数据结构。	固定。客户端必须使用预定义的 API 响应结构。
API 覆盖范围	完整。可访问 GitHub GraphQL API 提供的任何字段。	部分。仅限维护者硬编码的特定 REST 端点。
内省	内置。AI 可查询架构，动态了解新的 API 字段。	无。AI 依赖训练数据；若不更新工具，就无法发现新的 API 功能。
可维护性	无需修改代码即可更新。通常只需更新架构文件即可支持 GitHub 新功能。	需要大量编写代码。每项新功能都需要编写新的 Go 处理程序和结构体定义。
复杂度	需要 LLM 编写 GraphQL（架构内省工具提供支持）。	对于偏好简单函数调用的 LLM 来说更容易上手，但更难管理多次调用间的状态。

示例：要获取“项目的最新重要动态”，此工具可一次性获取发布信息、近期提交和未关闭议题；而官方服务可能需要调用工具 5 次以上，并进行多次往返。

为什么这对 AI Agent 很重要

1. 上下文窗口效率：官方工具通常会返回庞大的 JSON 对象（例如，完整的仓库对象可能超过 5KB）。使用 GraphQL，只需获取 name 和 description，即可节省 99% 的 Token。
2. 复杂推理：AI Agent 通常需要遍历关系（例如，“找出关闭此议题的 PR 的作者”）。使用 REST / 官方工具时，需要经过“搜索 -> 获取 ID -> 获取 PR -> 获取作者”的多步流程。使用 GraphQL 时，只需一次嵌套查询，AI 就能专注于推理，而不必处理数据传递。
3. 面向未来：当 GitHub 添加新功能时（例如，为 Discussions 添加新字段），此 MCP 服务可通过架构内省立即支持，而官方服务则需要等待代码更新。

前置条件

• Python 3.10 或更高版本
• GitHub personal access token（用于访问 GitHub API）
• Poetry（推荐的依赖管理工具）

安装与使用

我们建议使用 uv 进行管理。它目前是最快、最简单的 Python 项目管理工具。你也可以改用标准的 pip。

方法 1：使用 uv（推荐，最快）

使用 uv，无需手动创建虚拟环境或安装依赖；它会自动为你处理所有这些事项。

1. 安装 uv（如果已安装，请跳过）：

   # MacOS / Linux
   curl -lsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. 配置环境变量： 将 .env.example 复制为 .env，并填写你的 GitHub Token：

   cp .env.example .env
   # 编辑 .env 文件并填写你的 token
   

3. 一键运行：

   uv run github_graphql_api_mcp_server.py
   

   uv 会自动创建虚拟环境、下载并安装所有依赖，然后启动服务。

方法 2：使用标准 pip

如果你不想安装额外工具，可以使用传统的 Python 方法：

1. 创建并激活虚拟环境：

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   

2. 安装依赖：

   pip install -r requirements.txt
   

3. 配置环境变量： 按照上述说明创建并配置 .env 文件。

4. 运行：

   python github_graphql_api_mcp_server.py
   

在 Claude Desktop 中配置

你可以在 Claude 桌面应用中配置此 MCP 服务，以便一键启动：

1. 打开 Claude 桌面应用
2. 进入设置，找到 MCP 服务配置部分
3. 添加以下配置（根据你的实际路径进行修改）：

{
    "mcpServers": {
        "github_mcp": {
            "command": "/path/to/uv",
            "args": [
                "run",
                "--directory",
                "<project path>",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

配置示例（使用 uv）：

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

如果使用标准 Python（方法 2）：

{
    "mcpServers": {
        "github_mcp": {
            "command": "/path/to/project/.venv/bin/python",
            "args": [
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

配置完成后，你可以直接从 Claude 桌面应用启动 MCP 服务，无需手动启动。

可用工具

此服务提供以下工具：

1. print_type_field：查询 GitHub GraphQL 架构根类型的字段
2. graphql_schema_root_type：获取根类型（Query/Mutation）的文档
3. graphql_schema_type：查询特定类型的文档
4. call_github_graphql：执行 GitHub GraphQL API 查询

使用示例

通过 MCP 客户端连接到服务后，你可以：

1. 查询根类型文档：

   Use the graphql_schema_root_type tool, parameter type_name="QUERY"
   

2. 查询特定类型的字段：

   Use the print_type_field tool, parameters type_name="QUERY", type_fields_name="repository"
   

3. 查询特定类型的文档：

   Use the graphql_schema_type tool, parameter type_name="Repository"
   

4. 执行 GraphQL 查询：

   Use the call_github_graphql tool, parameter:
   graphql="""
   query {
     viewer {
       login
       name
     }
   }
   """
   

示例截图

以下是使用 Claude 调用 GitHub GraphQL API MCP 的示例：

注意事项

• 使用前请确保你的 GitHub token 具有适当的权限
• Token 存储在 .env 文件中，请勿将此文件提交到版本控制系统
• 查询应遵守 GitHub API 使用限制

许可证

本项目采用 MIT License 许可。这是一种宽松的许可证，允许用户自由使用、修改、分发和商业化本软件，但须保留版权声明和许可证声明。

详细条款请参阅 MIT 许可证。