AI导哈

GitHub GraphQL API查询工具

一个基于MCP协议的GitHub GraphQL API查询工具，提供高效的GitHub数据检索能力和模式探索功能。

  • by wanzunz
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 wanzunz/github_graphql_api_mcp

使用说明

GitHub GraphQL API MCP

英语 | 中文 | 日本语 | 西班牙语 | 法语

一种基于MCP（模型上下文协议）的工具，用于查询和使用GitHub GraphQL API。该项目提供了一个服务器，允许您探索GitHub GraphQL模式，并通过MCP客户端工具（如Claude AI）执行GraphQL查询。

目录

为什么使用GitHub GraphQL API

GitHub GraphQL API提供了优于传统REST API的显著优势：

  • 精确的数据检索：GraphQL允许客户端精确指定所需的字段，避免过多数据
  • 减少代币消耗：通过只请求必要的字段，API响应大小显著降低，降低了AI模型令牌消耗
  • 单一相关数据请求：一个查询可以检索多个相关资源，从而减少请求数量
  • 自我记录：通过内置的文档系统，您可以直接查询和理解API架构，而无需外部文档
  • 强类型系统：提供类型检查，减少错误

该项目利用这些优势提供工具，帮助您有效探索GitHub GraphQL API模式并执行优化的查询，为人工智能助手提供高效的GitHub数据检索功能。

应用场景

基本功能

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

  1. 存储库基本信息查询：获取存储库名称、描述、星数、分支列表和其他基本信息
  2. 问题数据检索：查询特定存储库的问题列表、详细信息或评论内容
  3. 用户配置文件访问：检索用户的个人资料、贡献统计数据和其他公共信息
  4. 拉取请求状态视图：获取PR基本状态、评论内容和合并信息
  5. 项目依赖关系查询：检索项目依赖项包列表和版本信息

探索高级功能

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

  1. 存储库贡献趋势分析：通过汇总提交数据、评估项目活动来分析代码更新频率和贡献者参与情况
  2. 问题管理和分类：根据自定义条件组织问题数据，发现需要优先处理的问题，提高项目管理效率
  3. 代码审查模式分析：分析PR评论和审查流程，确定常见问题模式，优化代码审查工作流程
  4. 贡献者网络可视化：在项目贡献者之间建立合作关系，发现关键贡献者和专业领域
  5. 依赖性健康评估：评估项目依赖关系的更新频率和潜在安全问题，提供依赖关系管理建议

特性

  • 查询GitHub GraphQL模式根类型（查询/变异）
  • 获取特定类型的详细文档
  • 查询特定字段的文档和参数
  • 直接执行GitHub GraphQL API查询，精确检索所需数据，减少代币消耗
  • 多语言支持（英语/中文/日语/西班牙语/法语）

与官方GitHub MCP服务器的比较

与官方相比 github mcp服务器，该项目在特定场景中具有明显优势：

功能 GitHub GraphQL API MCP 官方GitHub MCP服务器
核心机制 单个GraphQL查询 多个REST API/粒度工具
数据检索 一次性：在单个请求中获取存储库详细信息、问题、PR、历史记录和版本 多步骤：需要链接 search_repositories, get_file_contents, list_commits等等。
效率 高。最大限度地减少网络延迟和往返。 复杂数据收集的延迟较低。由于连续的工具调用，延迟较高。
令牌使用 优化。仅返回请求的字段。 更高中间工具输出（完整的JSON响应）消耗上下文窗口。
灵活性 高客户端定义所需的确切数据结构。 固定的.客户端必须使用预定义的API响应结构。
API覆盖范围 完成.访问GitHub的GraphQL API公开的任何字段。 部分的仅限于维护者硬编码的特定REST端点。
内省 内建.AI可以查询模式以动态地了解新的API字段。 无人工智能依赖于其训练数据；在没有工具更新的情况下无法发现新的API功能。
可维护性 零代码更新。通常只需要更新模式文件即可支持GitHub的新功能。 代码重。需要为每个新功能编写新的Go处理程序和结构定义。
复杂性 需要LLM编写GraphQL（由模式自检工具支持）。 对于喜欢简单函数调用的LLM来说更容易，但更难跨调用管理状态。

示例：要获取“项目的最新重要更新”，此工具可以在中获取发布、最近提交和打开的问题 一次走，而官方服务器可能需要5+个单独的工具调用和往返。

为什么这对AI代理很重要

  1. 上下文窗口效率：官方工具通常会返回大量的JSON对象（例如，一个完整的存储库对象可能是5KB+）。使用GraphQL，您只获取 name 和 description，节省99%的代币。
  2. 复杂推理：人工智能代理通常需要遍历关系（例如，“找到关闭此问题的PR的作者”）。在REST/官方工具中，这是一个多步骤的“搜索->获取ID->获取PR->获取作者”过程。在GraphQL中，它是一个嵌套查询，允许AI专注于推理而不是数据管道。
  3. 未来验证：当GitHub添加新功能（例如，讨论中的新字段）时，此MCP服务器可以通过模式自检立即支持它，而官方服务器则等待代码更新。

先决条件

  • Python 3.10或更高版本
  • GitHub个人访问令牌（用于访问GitHub API）
  • Poetry（推荐依赖关系管理工具）

安装与使用

我们建议使用 紫外线 用于管理，这是目前最快、最简单的Python项目管理工具。或者，您可以使用标准pip。

方法1：使用紫外线（推荐，最快）

使用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
# Edit .env file and fill in your 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桌面中配置

您可以在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：获取根类型的文档（查询/变异）
  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令牌具有适当的权限
  • 令牌存储在 .env 文件，不应提交到版本控制系统
  • 查询应符合GitHub API使用限制

许可证

该项目根据MIT许可证获得许可，这是一种非常宽松的许可证，允许用户自由使用、修改、分发和商业化该软件，只要他们保留版权声明和许可声明。

看 MIT许可证 详细条款。

相关 MCP