GitHub GraphQL API MCP

GitHub GraphQL API MCP

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

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

目录

• 应用场景
• 特性
• 先决条件
• 安装与使用
• 在Claude桌面中配置
• 可用工具
• 使用示例
• 备注
• 许可证

为什么使用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服务器的比较

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

示例：要获取“项目的最新重要更新”，此工具可以在中获取发布、最近提交和打开的问题 一次走，而官方服务器可能需要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"

1. 配置环境变量:

复制 .env.example 到 .env 并填写您的GitHub Token：

   cp .env.example .env
   # Edit .env file and fill in your token

1. 一键运行:

   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

1. 再进行:

   pip install -r requirements.txt

1. 配置环境变量:

创建和配置 .env 文件如上。

1. 跑:

   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",
                "
",
                "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"

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

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

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

   Use the graphql_schema_type tool, parameter type_name="Repository"

1. 执行GraphQL查询：

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

示例屏幕截图

下面是一个与Claude一起使用GitHub GraphQL API MCP的示例：

备注

• 使用前请确保您的GitHub令牌具有适当的权限
• 令牌存储在 .env 文件，不应提交到版本控制系统
• 查询应符合GitHub API使用限制

许可证

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

看 MIT许可证 详细条款。