GitHub GraphQL MCP 服务器

一个模型上下文协议 (MCP) 服务器，提供对 GitHub GraphQL API 的访问。 此服务器公开一个工具，允许针对 GitHub 的 API 执行任意 GraphQL 查询和变更。

功能

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

前提条件

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

安装

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

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

3. 安装依赖项：

   pip install -r requirements.txt
   

用法

运行服务器

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

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

使用 Claude for 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 for Desktop

常见错误

spawn python ENOENT

• 此错误表示未找到 Python 可执行文件
• 解决方案：使用虚拟环境中 Python 可执行文件的完整路径（例如，/path/to/your/.venv/bin/python）

ModuleNotFoundError: No module named 'httpx'（或其他软件包）

• Python 环境没有安装所需的依赖项
• 解决方案：确保您已激活虚拟环境并运行 pip install -r requirements.txt

Error: GitHub token not found in environment variables

• 服务器找不到您的 GitHub 令牌
• 解决方案：确保您已设置 GITHUB_TOKEN 环境变量

许可证

MIT