金大哥 - github-graphql-mcp-server MCP 详情

article

README

🚀 GitHub GraphQL MCP 服务器

GitHub GraphQL MCP 服务器是一个基于 Model Context Protocol (MCP) 的工具，它提供了对 GitHub GraphQL API 的便捷访问。借助该服务器，用户能够针对 GitHub 的 API 执行任意的 GraphQL 查询和变异操作。

🚀 快速开始

本服务器允许你对 GitHub 的 API 执行任意的 GraphQL 查询和变异。要使用它，你需要完成安装并配置相关环境。

✨ 主要特性

🔍 可执行任何针对 GitHub API 的 GraphQL 查询。
🛠️ 具备全面的错误处理和报告机制。
📄 拥有详细的文档，并附带示例查询。
📊 支持在 GraphQL 操作中使用变量。

📦 安装指南

先决条件

Python 3.10 或更高版本
GitHub 个人访问令牌 (PAT)

安装步骤

克隆此仓库。

设置虚拟环境（推荐）：

# 在 macOS/Linux 上
python3 -m venv .venv
source .venv/bin/activate

# 在 Windows 上
python -m venv .venv
.venv\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```

💻 使用示例

运行服务器

# 如果使用虚拟环境，请确保已激活
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate

# 使用你的 GitHub 令牌运行服务器
GITHUB_TOKEN=your_github_token_here python github_graphql_mcp_server.py

配置与 Claude Desktop

将以下内容添加到你的 Claude Desktop 配置文件中：

{
  "github-graphql": {
    "command": "/absolute/path/to/your/.venv/bin/python",
    "args": [
        "/absolute/path/to/github_graphql_mcp_server.py"
    ],
    "options": {
        "cwd": "/absolute/path/to/repository"
    },
    "env": {
        "GITHUB_TOKEN": "your_github_token_here"
    }
  }
}

请替换 /absolute/path/to/ 为你的服务器文件的实际路径，并添加你的 GitHub 令牌。

基础用法

获取仓库信息

query GetRepo($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    name
    description
    stargazerCount
    url
    createdAt
    owner {
      login
      avatarUrl
    }
  }
}

变量：

{
  "owner": "octocat",
  "name": "Hello-World"
}

搜索仓库

query SearchRepos($query: String!, $first: Int!) {
  search(query: $query, type: REPOSITORY, first: $first) {
    repositoryCount
    edges {
      node {
        ... on Repository {
          name
          owner { login }
          description
          stargazerCount
          url
        }
      }
    }
  }
}

变量：

{
  "query": "language:python stars:1000",
  "first": 5
}

获取用户信息

query GetUserInfo($login: String!) {
  user(login: $login) {
    name
    login
    bio
    avatarUrl
    followers {
      totalCount
    }
    repositories(first: 5, orderBy: {field: STARGAZERS, direction: DESC}) {
      nodes {
        name
        description
        stargazerCount
      }
    }
  }
}

变量：

{
  "login": "octocat"
}

📚 详细文档

GitHub API 速率限制

注意 GitHub 的 API 速率限制：

已身份验证的请求：每小时 5,000 次请求
未身份验证的请求：每小时 60 次请求

故障排除

如果你遇到问题，请按以下步骤排查：

检查你的 GitHub 令牌是否有正确的权限。
确保你的虚拟环境已正确设置并激活。
确保你的令牌在环境变量中正确设置。
如果使用 Claude Desktop，请确保 Python 的路径是正确的（使用虚拟环境 Python 的绝对路径）。
查看服务器日志中的错误消息。
确保你的 GraphQL 查询与 GitHub 的架构有效。
在进行配置更改后重启 Claude Desktop。

常见错误

spawn python ENOENT

该错误表示找不到 Python 可执行文件。
解决方案：使用虚拟环境中的 Python 可执行文件的绝对路径（例如 /path/to/your/.venv/bin/python）。

ModuleNotFoundError: No module named 'httpx' (或其他包)

解决方案：运行 pip install -r requirements.txt 来安装缺失的依赖项。

GITHUB_TOKEN 不可为空 或类似错误

确保在环境变量中设置了有效的 GitHub 令牌。

github-graphql-mcp-server