GitHub MCP Server

GitHub MCP Server

Claude Desktop のような AI アシスタント向けに、GitHub 連携ツールを提供する Spring Boot ベースの Model Context Protocol（MCP）サーバーです。

概要

このサーバーは Model Context Protocol を実装し、MCP クライアントが使用できるツールとして GitHub の操作を公開します。GitHub CLI（gh）を活用して、リポジトリ管理、イシュー追跡、プルリクエスト管理など、さまざまな GitHub 操作を実行します。Docker を必要としない、公式 GitHub MCP サーバーの軽量な代替手段です。

Claude Desktop のクイックスタート

このサーバーを Claude Desktop で使用するには、Claude の設定ファイルに次の内容を追加してください。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
      "env": {}
    }
  }
}

/path/to/gh_mcp_server をプロジェクトディレクトリの実際のパスに置き換えてください。

機能

リポジトリ操作

• 認証済みユーザーのリポジトリを一覧表示
• GitHub 上のリポジトリを検索
• リポジトリの詳細情報を取得
• リポジトリ内のブランチを一覧表示
• ブランチを新規作成
• リポジトリからファイルの内容を取得
• コミット履歴を取得

イシュー管理

• イシューを一覧表示（オープン、クローズ、またはすべて）
• イシューの詳細情報を取得
• イシューを新規作成
• イシューをクローズ
• イシューにコメントを追加
• イシューのタイトルと本文を編集

プルリクエスト管理

• プルリクエストを一覧表示
• プルリクエストの詳細情報を取得
• プルリクエストを新規作成
• プルリクエストをマージ（マージ、スカッシュ、またはリベース）
• プルリクエストをクローズ
• プルリクエストにコメントを追加

ワークフローと Actions

• リポジトリ内のワークフローを一覧表示
• 絞り込み条件を指定してワークフローの実行を一覧表示
• ワークフロー実行の詳細情報を表示

リリース管理

• リリースを一覧表示
• リリースの詳細を表示
• リリースを新規作成（ドラフト／プレリリースのオプションあり）

ユーザー操作

• 認証済みユーザーの詳細情報を取得

前提条件

• Java 21 以上 - 最新の Java 機能（仮想スレッド、レコード、パターンマッチング）を使用します
• GitHub CLI（gh） - インストールおよび認証が必要です
• Gradle - プロジェクトにラッパーが含まれています

この MCP サーバーを使う理由

• 🚀 軽量：Docker 不要の純粋な Java 実装です
• 🔧 包括的：一連のワークフローを網羅する 26 種類の GitHub 操作に対応しています
• ⚡ 高速：最適化された JSON レスポンスによる GitHub CLI との直接連携です
• 🧪 十分なテスト：信頼性を確保する 75 件以上のテストケースがあります
• 🛡️ セキュア：既存の GitHub CLI 認証を活用します

セットアップ

1. GitHub CLI をインストール

   # macOS
   brew install gh
   
   # or download from https://cli.github.com/
   

2. GitHub で認証

   gh auth login
   

3. プロジェクトをクローンしてビルド

   git clone <repository-url>
   cd gh_mcp_server
   ./gradlew build
   

   注：ビルド時に、バージョンに依存しないシンボリックリンク gh_mcp_server.jar → gh_mcp_server-1.0.0.jar が自動的に作成されます。

4. Claude Desktop を設定

   ビルド後、この MCP サーバーを使用するよう Claude を設定します。次の 2 つの方法があります。

   方法 A：JAR ファイルを使用（推奨）

   {
     "mcpServers": {
       "github": {
         "command": "java",
         "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
         "env": {}
       }
     }
   }
   

   注：シンボリックリンク gh_mcp_server.jar は現在のバージョン（gh_mcp_server-1.0.0.jar）を指します。これにより、バージョンに依存しないデプロイが可能になります。特定のバージョンを指定してデプロイする場合は、代わりにバージョン付きのファイル名を使用してください。

   方法 B：Gradle を使用

   {
     "mcpServers": {
       "github": {
         "command": "./gradlew",
         "args": ["bootRun"],
         "cwd": "/path/to/gh_mcp_server",
         "env": {}
       }
     }
   }
   

5. 新しいサーバー設定を読み込むため、Claude Desktop を再起動します

使用例

Claude Desktop の設定後、自然言語で GitHub を操作できます。

リポジトリ管理

• 「自分のリポジトリを一覧表示して」 → 詳細情報とともにリポジトリを表示します
• 「自分のプライベートリポジトリを一覧表示して」 → 可視性（パブリック／プライベート／内部）で絞り込みます
• 「スター数が 1000 を超える Spring Boot リポジトリを検索して」
• 「microsoft/vscode リポジトリの詳細を表示して」
• 「自分のプロジェクトリポジトリから直近 5 件のコミットを取得して」
• 「自分のプロジェクトリポジトリにはどんなブランチがある？」

イシュー管理

• 「プロジェクトのオープンなイシューを一覧表示して」 → 現在オープンなイシューを一覧表示します
• 「イシュー #123 の詳細を表示して」 → 特定のイシュー情報を取得します
• 「タイトルを『Bug: Login fails』、説明を……として新しいイシューを作成して」
• 「イシュー #123 をクローズして、『Fixed in latest release』というコメントを追加して」

プルリクエスト管理

• 「kubernetes/kubernetes リポジトリのすべてのプルリクエストを一覧表示して」
• 「PR #456 の詳細を表示して」
• 「feature-branch から main へのプルリクエストを作成して」
• 「squash 戦略を使って PR #789 をマージして」

CI/CD とリリース

• 「このリポジトリのすべてのワークフローを表示して」 → GitHub Actions を一覧表示します
• 「最近のワークフロー実行のステータスは？」
• 「golang/go リポジトリのリリースを一覧表示して」
• 「v2.1.0 の新しいリリースをドラフトとして作成して」

ファイル操作

• 「プロジェクトの package.json の内容を取得して」
• 「main ブランチの README ファイルを表示して」

検証

サーバーの起動に失敗する場合は、次の点を確認してください。

• Java 21 以降がインストールされ、PATH に設定されている
• GitHub CLI がインストールされ、認証されている（gh auth status）
• 設定内の JAR ファイルのパスが正しい
• Claude Desktop を再起動している

サーバーのテスト

サーバーを単独で（Claude を使わずに）テストするには、次のようにします。

./gradlew bootRun

サーバーは STDIO モードで起動し、MCP プロトコルのメッセージを待ち受けます。ただし、通常の使用では、上記のように Claude Desktop がサーバーを自動的に実行するよう設定してください。

開発コマンド

# Build the project and run all tests
./gradlew build

# Run tests (command syntax validation only)
./gradlew test

# Run tests including GitHub CLI integration tests
./gradlew test -Dtest.gh.integration=true

# Format code with Spotless (Google Java Format)
./gradlew spotlessApply

# Check code formatting without applying changes
./gradlew spotlessCheck

# Clean build artifacts
./gradlew clean

# Run the server locally for testing
./gradlew bootRun

テストカバレッジ

このプロジェクトには、包括的なテストカバレッジが含まれています。

• 75 件以上のテストケースで、26 種類すべての GitHub 操作を検証
• コマンド構文テスト - gh コマンドが正確に構成されることを検証
• エッジケーステスト - 特殊文字、Unicode、null 値を処理
• 統合テスト - 実際の GitHub CLI の実行（任意）
• エラー処理テスト - 適切な障害処理を検証

テストに関する詳しいドキュメントは、src/test/java/com/kousenit/gh_mcp_server/TEST_README.md を参照してください。

設定

サーバーは Spring Boot のデフォルト設定を使用します。src/main/resources/application.properties で設定をカスタマイズできます。

主な設定オプション

• github.defaultBranch - 操作に使用するデフォルトのブランチ名（デフォルト：main）
• spring.threads.virtual.enabled - パフォーマンス向上のため仮想スレッドを有効にする（デフォルト：true）
• MCP サーバーは CLI 統合のために STDIO モードで動作します

利用可能な操作（全 26 種類）

リポジトリ操作

• listRepositories - 公開／プライベート／内部の任意の可視性フィルターを指定して、ユーザーのリポジトリを一覧表示
• searchRepositories - GitHub リポジトリを検索
• getRepository - リポジトリの詳細情報を取得
• getCommitHistory - 指定可能な上限数で、リポジトリのコミット履歴を取得
• listBranches - リポジトリのブランチを一覧表示
• createBranch - 新しいブランチを作成

イシュー管理

• listIssues - リポジトリのイシューを一覧表示
• getIssue - 特定のイシューの詳細を取得
• createIssue - 新しいイシューを作成
• closeIssue - イシューをクローズ
• commentOnIssue - イシューにコメントを追加
• editIssue - イシューのタイトル／本文を編集

プルリクエスト管理

• listPullRequests - プルリクエストを一覧表示
• getPullRequest - PR の詳細を取得
• createPullRequest - 新しいプルリクエストを作成
• mergePullRequest - PR をマージ（merge／squash／rebase）
• closePullRequest - プルリクエストをクローズ
• commentOnPullRequest - PR にコメントを追加

ワークフローと CI/CD

• listWorkflows - リポジトリのワークフローを一覧表示
• listWorkflowRuns - フィルタリングしてワークフローの実行を一覧表示
• getWorkflowRun - ワークフロー実行の詳細を取得

リリース管理

• listReleases - リポジトリのリリースを一覧表示
• getRelease - リリースの詳細を取得
• createRelease - 新しいリリースを作成（ドラフト／プレリリースのオプション）

ファイルとユーザーの操作

• getFileContents - リポジトリからファイルの内容を取得
• getMe - 認証済みユーザーの詳細を取得

すべての操作は最適化された JSON レスポンスを返し、包括的なエラー処理に対応しています。

トラブルシューティング

よくある問題

「gh: command not found」

• https://cli.github.com/ から GitHub CLI をインストールします
• gh がシステムの PATH に含まれていることを確認します
• gh --version でテストします

認証エラー

• gh auth login を実行して認証します
• gh auth status で状態を確認します
• アクセスしようとしているリポジトリへのアクセス権があることを確認します

サーバーの起動失敗

• Java 21 以降がインストールされていることを確認します：java --version
• Claude の設定で JAR ファイルのパスを確認します
• Claude Desktop のログでエラーメッセージを確認します
• サーバーが別のインスタンスですでに実行されていないことを確認します

コマンドのタイムアウト

• 大規模なリポジトリやネットワークの遅さがタイムアウトの原因になることがあります
• タイムアウトのデフォルトは操作ごとに 30 秒です
• インターネット接続と GitHub API のステータスを確認します

権限拒否エラー

• GitHub CLI にリポジトリへの適切な権限があることを確認します
• 組織のリポジトリの場合は、適切なアクセス権があるか確認します
• 一部の操作には書き込み権限が必要です（作成、編集、マージ、クローズ）

パフォーマンスのヒント

• 応答を速くするため、リポジトリ名とオーナー名を指定します
• 適切な上限パラメーターを使用して検索結果を制限します
• サーバーは最適な並行パフォーマンスを実現するため、仮想スレッドを使用します
• GitHub CLI はレート制限を自動的に処理します

ヘルプの利用

• GitHub CLI のドキュメントを確認します：gh help
• MCP プロトコルを確認します：https://modelcontextprotocol.io/
• サーバーの問題については、application.properties でデバッグログを有効にします

デプロイに関する考慮事項

JAR のバージョン管理

ビルドプロセスでは、ファイル名にバージョン番号を含む JAR ファイル（例：gh_mcp_server-1.0.0.jar）が生成されます。デプロイまたは更新する際は、次の点に注意してください。

1. 初回デプロイ：Claude Desktop の設定で現在のバージョンを使用します：

   "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server-1.0.0.jar"]
   

2. バージョンの更新：新しいバージョンに更新する際は、次の作業が必要です。

   • 新しいバージョンをビルドします：./gradlew build
   • Claude Desktop の設定を新しい JAR ファイル名に更新します
   • Claude Desktop を再起動して新しいバージョンを読み込みます

3. バージョンに依存しないデプロイ：デプロイを簡単にするには、次の方法を利用できます。

   • 自動生成されるシンボリックリンク gh_mcp_server.jar（ビルド時に自動作成）を使用します
   • Gradle オプションを使用します（最新のビルドが自動的に使用されます）
   • バージョン更新を処理するデプロイスクリプトを使用します

   シンボリックリンクの自動管理：ビルドプロセスでは、シンボリックリンクが自動的に作成および管理されます。

   • ./gradlew build は gh_mcp_server.jar → gh_mcp_server-X.Y.Z.jar を作成します
   • ./gradlew clean build は正しいバージョンのシンボリックリンクを再作成します
   • シンボリックリンクを手動で管理する必要はありません

設定管理

• Claude Desktop の設定をバージョン管理下に置きます
• 本番環境で使用する JAR のバージョンを記録します
• デプロイスクリプトでパスに環境変数を使用することを検討します

技術スタック

• Spring Boot 3.5.0 - アプリケーションフレームワーク
• Spring AI 1.0.0 - AI 統合および MCP サーバー機能
• Java 21 - 仮想スレッドをサポートするプログラミング言語
• GitHub CLI - GitHub API 統合
• Gradle - ビルドツール
• Spotless - Google Java Format によるコード整形

主な実装機能

• 仮想スレッド（Java 21） - 効率的な並行 I/O 操作
• ProcessBuilder - タイムアウトをサポートする安全なコマンド実行
• レコード（Java 17） - コマンド結果のための不変データ構造
• パターンマッチング - 型チェックのための最新の Java 構文
• 文字列テンプレート - より簡潔な文字列構築のために String.formatted() を使用

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。