GitHub GraphQL API MCP

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

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

为什么使用GitHub GraphQL API

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

• 精确的数据检索：GraphQL允许客户端指定它们需要的确切字段，避免了多余的数据
• 减少Token消耗：通过仅请求必要的字段，API响应大小显著减小，降低了AI模型的Token消耗
• 单次请求获取相关数据：一个查询可以检索多个相关资源，减少了请求数量
• 自文档化：通过其内置的文档系统，您可以直接查询和理解API模式，无需外部文档
• 强大的类型系统：提供类型检查，减少错误

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

应用场景

基本功能

该工具轻松实现了以下常见操作：

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

探索性高级功能

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

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

特性

• 查询GitHub GraphQL模式根类型（Query/Mutation）
• 获取特定类型的详细文档
• 查询特定字段的文档和参数
• 直接执行GitHub GraphQL API查询，精确检索所需数据，减少Token消耗
• 双语支持（英语/中文）

先决条件

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

安装

1. 克隆仓库：

bash
git clone https://github.com/wanzunz/github_graphql_api_mcp.git
cd github_graphql_api_mcp

1. 使用Poetry安装依赖项：

bash

如果尚未安装Poetry，请先安装：

curl -sSL https://install.python-poetry.org | python3 -

使用Poetry安装依赖项

poetry install

激活虚拟环境

poetry shell

如果您不使用Poetry，可以使用传统方法：

bash

创建并激活虚拟环境

python -m venv .venv
source .venv/bin/activate # Linux/MacOS

或

.venvScriptsactivate # Windows

安装依赖项

pip install -e .3. 配置环境变量：

创建一个 .env 文件，并添加您的 GitHub 个人访问令牌：

GITHUB_TOKEN="your_github_token_here"

您可以复制 .env.example 文件来创建它：

bash
cp .env.example .env

然后编辑 .env 文件，将 your_github_token_here 替换为您的实际 GitHub 令牌。

使用方法

启动服务器

确保您已经激活了 Poetry 虚拟环境 (poetry shell)，然后：

运行

bash
python github_graphql_api_mcp_server.py

服务器启动后，您可以通过 MCP 客户端（例如 Claude AI）连接到它。

在 Claude 桌面应用中配置

您可以在 Claude 桌面应用程序中配置此 MCP 服务器以实现一键启动：

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

json
{
"mcpServers": {
"github_mcp": {
"command": "",
"args": [
"--directory",
"",
"run",
"github_graphql_api_mcp_server.py"
]
}
}
}

配置示例：

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

如果您使用 conda 或其他环境管理工具：

json
{
"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 服务器，而无需手动启动。

可用工具

服务器提供了以下工具：

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. 查询根类型文档：

   使用 graphql_schema_root_type 工具，参数 type_name="QUERY"

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

   使用 print_type_field 工具，参数 type_name="QUERY", type_fields_name="repository"

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

   使用 graphql_schema_type 工具，参数 type_name="Repository"

4. 执行 GraphQL 查询：

   使用 call_github_graphql 工具，参数：
   graphql="""
   query {
   viewer {
   login
   name
   }
   }
   """

示例截图

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

注意事项

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

许可证

本项目采用 MIT 许可证 - 这是一个非常宽松的许可证，允许用户自由使用、修改、分发和商业化该软件，只要保留版权声明和许可声明即可。

详见 MIT 许可证。