GitHub GraphQL MCP 服务器

这是一个提供访问 GitHub GraphQL API 的 Model Context Protocol (MCP) 服务器。此服务器公开了一个工具，允许执行任意的 GraphQL 查询和突变操作针对 GitHub 的 API。

功能

• 执行任何针对 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 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