GitHub GraphQL MCP 服务器

一个提供对 GitHub GraphQL API 访问的 Model Context Protocol (MCP) 服务器。该服务器提供了一个工具，允许对 GitHub 的 API 执行任意的 GraphQL 查询和变异。

特性

• 执行任何针对 GitHub API 的 GraphQL 查询
• 全面的错误处理和报告
• 详细的文档附带示例查询
• 支持 GraphQL 操作中的变量

先决条件

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

安装

1. 克隆此仓库
2. 设置虚拟环境（推荐）：

   # 在 macOS/Linux 上
   python3 -m venv .venv
   source .venv/bin/activate
   
   # 在 Windows 上
   python -m venv .venv
   .venv\Scripts\activate
   

3. 安装依赖项：

   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 次请求

故障排除

如果你遇到问题：

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