GitHub GraphQL MCP Server

GitHub GraphQL MCP 服务

一个可访问 GitHub GraphQL API 的模型上下文协议（MCP）服务。该服务提供一个工具，用于对 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
   

使用方法

运行服务

# If using a virtual environment, make sure it's activated
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server with your GitHub token
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