Github Graphql MCP Server

🚀 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)。

安裝步驟

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 令牌。