GitHub GraphQL API MCP

GitHub GraphQL API MCP

英語 | 中国語 | 日本語 | スペイン語 | フランス語

GitHub GraphQL API のクエリと利用のための、MCP（Model Context Protocol）ベースのツールです。このプロジェクトでは、MCP クライアントのツール（Claude AI など）を通じて、GitHub GraphQL スキーマを調べたり、GraphQL クエリを実行したりできるサーバーを提供します。

目次

• GitHub GraphQL API を利用する理由
• 活用シナリオ
• 機能
• 公式 GitHub MCP サーバーとの比較
• 前提条件
• インストールと使用方法
• Claude Desktop での設定
• 利用可能なツール
• 使用例
• 注意事項
• ライセンス

GitHub GraphQL API を利用する理由

GitHub GraphQL API には、従来の REST API と比べて大きな利点があります。

• 正確なデータ取得：GraphQL では、クライアントが必要なフィールドを正確に指定できるため、過剰なデータ取得を避けられます。
• トークン消費量の削減：必要なフィールドのみをリクエストすることで、API のレスポンスサイズが大幅に小さくなり、AI モデルのトークン消費量を抑えられます。
• 関連データを単一のリクエストで取得：1 つのクエリで複数の関連リソースを取得できるため、リクエスト数を減らせます。
• 自己文書化：組み込みのドキュメントシステムを通じて、外部ドキュメントを参照せずに API スキーマを直接クエリし、理解できます。
• 強力な型システム：型チェックにより、エラーを減らせます。

このプロジェクトでは、こうした利点を活用し、GitHub GraphQL API スキーマを効果的に調べ、最適化されたクエリを実行するためのツールを提供します。これにより、AI アシスタントは GitHub データを効率的に取得できます。

活用シナリオ

基本機能

このツールを使うと、次のような一般的な操作を簡単に実行できます。

1. リポジトリの基本情報のクエリ：リポジトリ名、説明、スター数、ブランチ一覧などの基本情報を取得します。
2. Issue データの取得：特定のリポジトリの Issue 一覧、詳細、コメント内容をクエリします。
3. ユーザープロフィールへのアクセス：ユーザーのプロフィール、コントリビューション統計などの公開情報を取得します。
4. プルリクエストのステータス確認：PR の基本ステータス、コメント内容、マージ情報を取得します。
5. プロジェクトの依存関係のクエリ：プロジェクトの依存パッケージ一覧とバージョン情報を取得します。

応用的な分析機能の検討

GraphQL の柔軟なクエリ機能を活用すると、次のような高度な分析機能も実装できます。

1. リポジトリのコントリビューション傾向分析：コミットデータを集計してコードの更新頻度とコントリビューターの参加状況を分析し、プロジェクトの活発度を評価します。
2. Issue の管理と分類：カスタム条件に基づいて Issue データを整理し、優先的に対処すべき問題を見つけ、プロジェクト管理の効率を高めます。
3. コードレビューのパターン分析：PR のコメントとレビューのプロセスを分析し、よくある問題のパターンを特定して、コードレビューのワークフローを最適化します。
4. コントリビューターのネットワークの可視化：プロジェクトのコントリビューター間の協力関係を構築し、主要なコントリビューターや専門分野を見つけます。
5. 依存関係の健全性評価：プロジェクトの依存関係の更新頻度や潜在的なセキュリティ上の問題を評価し、依存関係の管理に関する提案を行います。

機能

• GitHub GraphQL スキーマのルート型（Query/Mutation）をクエリ
• 特定の型の詳細なドキュメントを取得
• 特定のフィールドのドキュメントとパラメーターをクエリ
• GitHub GraphQL API のクエリを直接実行し、必要なデータを正確に取得してトークン消費量を削減
• 多言語対応（英語／中国語／日本語／スペイン語／フランス語）

公式 GitHub MCP サーバーとの比較

公式の github-mcp-server と比べて、このプロジェクトには、特定のシナリオで際立った利点があります。

機能	GitHub GraphQL API MCP	公式 GitHub MCP サーバー
中核となる仕組み	単一の GraphQL クエリ	複数の REST API／詳細なツール
データ取得	一度で完了：リポジトリの詳細、Issue、PR、履歴、リリースを1回のリクエストで取得	複数ステップ：search_repositories、get_file_contents、list_commits などを連携させる必要があります
効率性	高い。ネットワーク遅延と往復回数を最小限に抑えます。	複雑なデータ収集では低くなります。ツール呼び出しを順次行うため、遅延が大きくなります。
トークン使用量	最適化済み。要求されたフィールドのみを返します。	多くなります。中間ツールの出力（完全な JSON レスポンス）がコンテキストウィンドウを消費します。
柔軟性	高い。クライアントが必要なデータ構造を正確に定義できます。	固定。クライアントは事前定義された API レスポンス構造に対応する必要があります。
API 対応範囲	完全。GitHub の GraphQL API が公開する任意のフィールドにアクセスできます。	部分的。メンテナーがハードコードした特定の REST エンドポイントに限られます。
イントロスペクション	組み込み。AI はスキーマをクエリして、新しい API フィールドを動的に把握できます。	なし。AI はトレーニングデータに依存し、ツールの更新なしでは新しい API 機能を発見できません。
保守性	コード変更不要の更新。新しい GitHub 機能への対応には、スキーマファイルの更新だけで済むことがよくあります。	コード中心。新機能ごとに、新しい Go ハンドラーと構造体定義を作成する必要があります。
複雑さ	LLM が GraphQL を記述する必要があります（スキーマイントロスペクションツールがサポートします）。	シンプルな関数呼び出しを好む LLM には扱いやすい一方、呼び出し間での状態管理は難しくなります。

例：「プロジェクトの最新の重要な更新情報」を取得する場合、このツールならリリース、最近のコミット、未解決の Issue を一度の操作で取得できます。一方、公式サーバーでは5回以上の個別のツール呼び出しと往復が必要になることがあります。

AI エージェントにとって重要な理由

1. コンテキストウィンドウの効率性：公式ツールは巨大な JSON オブジェクトを返すことがよくあります（例：リポジトリ全体のオブジェクトは5KB以上になる場合があります）。GraphQL では name と description のみを取得できるため、トークンを99％節約できます。
2. 複雑な推論：AI エージェントは、関連性をたどる必要があることがよくあります（例：「この Issue をクローズした PR の作成者を見つける」）。REST／公式ツールでは、「検索 -> ID を取得 -> PR を取得 -> 作成者を取得」という複数ステップの処理になります。GraphQL では、ネストした単一のクエリで実行できるため、AI はデータの受け渡しではなく推論に集中できます。
3. 将来への対応：GitHub に新機能（例：Discussions の新しいフィールド）が追加された場合、この MCP サーバーはスキーマイントロスペクションを通じてすぐに対応できますが、公式サーバーではコードの更新を待つ必要があります。

前提条件

• Python 3.10 以降
• GitHub の個人アクセストークン（GitHub API へのアクセスに使用）
• Poetry（推奨される依存関係管理ツール）

インストールと使い方

現在、最も高速でシンプルな Python プロジェクト管理ツールである uv の使用をおすすめします。代わりに、標準の pip も使用できます。

方法 1：uv を使用する（推奨・最速）

uv を使用すると、仮想環境を手動で作成したり、依存関係をインストールしたりする必要はありません。すべて自動で処理されます。

1. uv をインストールする（すでにインストール済みの場合はスキップしてください）：

   # MacOS / Linux
   curl -lsSf https://astral.sh/uv/install.sh | sh
   
   # Windows
   powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
   

2. 環境変数を設定する： .env.example を .env にコピーし、GitHub Token を入力します：

   cp .env.example .env
   # .env ファイルを編集してトークンを入力します
   

3. ワンクリックで実行する：

   uv run github_graphql_api_mcp_server.py
   

   uv が仮想環境を自動で作成し、すべての依存関係をダウンロードしてインストールした後、サーバーを起動します。

方法 2：標準の pip

追加のツールをインストールしたくない場合は、従来の Python の方法を使用できます：

1. 仮想環境を作成して有効化する：

   python -m venv .venv
   source .venv/bin/activate  # Windows: .venv\Scripts\activate
   

2. 依存関係をインストールする：

   pip install -r requirements.txt
   

3. 環境変数を設定する： 上記と同様に .env ファイルを作成して設定します。

4. 実行する：

   python github_graphql_api_mcp_server.py
   

Claude Desktop で設定する

この MCP サーバーは Claude デスクトップアプリで設定すると、ワンクリックで起動できます：

1. Claude デスクトップアプリを開きます
2. 設定に移動し、MCP サーバーの設定セクションを探します
3. 次の設定を追加します（実際のパスに合わせて変更してください）：

{
    "mcpServers": {
        "github_mcp": {
            "command": "/path/to/uv",
            "args": [
                "run",
                "--directory",
                "<project path>",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

設定例（uv を使用する場合）：

{
    "mcpServers": {
        "github_mcp": {
            "command": "/Users/username/.cargo/bin/uv",
            "args": [
                "run",
                "--directory",
                "/Users/username/github/github_graphql_api_mcp/",
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

標準の Python を使用する場合（方法 2）：

{
    "mcpServers": {
        "github_mcp": {
            "command": "/path/to/project/.venv/bin/python",
            "args": [
                "github_graphql_api_mcp_server.py"
            ]
        }
    }
}

設定後は、手動で起動しなくても、Claude デスクトップアプリから MCP サーバーを直接起動できます。

利用可能なツール

このサーバーでは、次のツールを利用できます：

1. print_type_field：GitHub GraphQL スキーマのルート型のフィールドを照会します
2. graphql_schema_root_type：ルート型（Query/Mutation）のドキュメントを取得します
3. graphql_schema_type：特定の型のドキュメントを照会します
4. call_github_graphql：GitHub GraphQL API のクエリを実行します

使用例

MCP クライアントでサーバーに接続すると、次の操作ができます：

1. ルート型のドキュメントを照会する：

   Use the graphql_schema_root_type tool, parameter type_name="QUERY"
   

2. 特定の型のフィールドを照会する：

   Use the print_type_field tool, parameters type_name="QUERY", type_fields_name="repository"
   

3. 特定の型のドキュメントを照会する：

   Use the graphql_schema_type tool, parameter type_name="Repository"
   

4. GraphQL クエリを実行する：

   Use the call_github_graphql tool, parameter:
   graphql="""
   query {
     viewer {
       login
       name
     }
   }
   """
   

スクリーンショットの例

以下は、Claude で GitHub GraphQL API MCP を使用する例です：

注意事項

• 使用前に、GitHub トークンに適切な権限があることを確認してください
• トークンは .env ファイルに保存されます。このファイルをバージョン管理システムにコミットしないでください
• クエリは GitHub API の使用制限を遵守してください

ライセンス

このプロジェクトは MIT License の下でライセンスされています。著作権表示とライセンス条項を保持する限り、ユーザーが本ソフトウェアを自由に使用、変更、配布、商用利用できる、非常に寛容なライセンスです。

詳細な条項については、MIT License を参照してください。