github-mcp-gateway

任意のMCPクライアントに、認証済みGitHubアクセス — リポジトリ、イシュー、プルリクエスト、ファイル内容、検索 — を、本物のOAuth 2.1ハンドシェイクを通じて提供するリモートMCPサーバー。Cloudflare Workers上で動作します。

Claude Code、Claude.ai / Cowork、および仕様準拠の任意のMCPクライアントで動作します。認証はGitHub Appのuser-to-serverフローです。そのため、このサーバーが到達できるリポジトリは、GitHub自身のインストール画面でチェックを入れたものだけです — アカウントが閲覧できるすべてではありません。

**これはサインアップして使うサービスではなく、自分で実行するソースです。**共有インスタンスはありません。自分のGitHub Appに対して自分のWorkerをデプロイするので、認証情報がアカウントの外に出ることはありません — 設計上の制限を参照。セットアップはスクリプト1つで約10分です：

git clone https://github.com/mazze93/github-mcp-gateway
cd github-mcp-gateway && ./scripts/setup.sh <your-github-login>

機能概要

Related MCP server: Cloudflare GitHub OAuth MCP Server

存在理由と構成

MCPクライアントは、あなたの認証情報を使ってGitHubのAPIに直接通信することはできません — (a) 誰が要求しているかを証明し、(b) 実際のGitHubトークンを保持し、(c) ツール呼び出しをGitHub APIリクエストに変換する、何かが間に必要です。このWorkerがその中間層であり、同時に2つのOAuthロールを担います：

• GitHubに対するOAuthクライアント（上流） — GitHub自身の同意画面にあなたを誘導し、その結果得られたコードをトークンと交換します。

• MCPクライアントに対するOAuthサーバー（下流） — クライアントがあなたのGitHubトークンを見ることはありません。クライアントはこのWorkerから、このWorker専用にスコープされた独自のトークンを取得します。@cloudflare/workers-oauth-provider（Cloudflare自身のライブラリ）がその下流側を実装しています：OAuth 2.1、PKCE、Dynamic Client Registration（DCR）です。特にDCRは、クライアントが初回接続時に、あなたが手動で認証情報を作成することなく自己登録できるようにするものです。

MCP client ──OAuth (DCR, PKCE)──▶ this Worker ──OAuth (GitHub App)──▶ GitHub
                                       │
                                       ▼
                               Workers KV (OAUTH_KV)
                           state · refresh tokens · approved clients

クラシックなOAuth AppではなくGitHub Appを使う理由

Cloudflare自身のテンプレートはクラシックなOAuth Appを使用していますが、これはよりシンプルである一方、リポジトリのスコープが全か無かであり、自分で有効期限を実装しない限り期限切れにならないトークンを提供します。このビルドでは代わりに、user-to-serverトークンフローを備えたGitHub Appを使用します：

• インストール時のリポジトリ単位のスコープ指定 — このサーバーがアクセスできるリポジトリを正確に選択します（GitHub自身のインストールピッカー）。「このアカウントが閲覧できるすべて」ではありません。

• 実際に期限切れになり、自動更新されるトークン — 「Expire user authorization tokens」（ユーザー認証トークンの期限切れ）をオンにすると、GitHubは8時間のアクセストークンと6か月のリフレッシュトークンを返します。リフレッシュトークンを使用すると、その両方の新しいペアが発行されます。このサーバーを6か月に1回以上使用している限り、トークンは陳腐化せず、手動で新しいトークンを発行する必要もありません。

この更新サイクルは、このWorkerとのCowork独自のセッションとは独立に、src/github-client.tsによって処理されます — 後述のトークンのライフサイクルを参照。

1. GitHub Appを作成する

github.com/settings/apps/new（個人アカウント）またはgithub.com/organizations//settings/apps/new（組織所有 — 個人アカウントではなく組織の下に置きたい場合はこちらを使用します）にアクセスします。

作成後：

1. アプリの設定ページ上部にあるClient IDを控えます。

2. Generate a new client secretをクリックします — 今すぐコピーしてください。一度しか表示されません。

3. Optional featuresの下にあるUser-to-server token expiration（ユーザー対サーバートークンの期限切れ）を見つけ、Opt-inをクリックします。これがリフレッシュトークンを存在させる唯一の要因です — これをスキップすると、サーバーはコールバックの手順で「戻ってこれを行ってください」と指示する明確なエラーを出して失敗します。

4. Install App（左サイドバー）に移動し、アカウントにインストールします。Only select repositories（選択したリポジトリのみ）を選択し、このサーバーにアクセスさせたいリポジトリを選んでください（後で同じ画面から追加できます）。

デプロイ前にローカルでwrangler devを使って反復開発する予定がある場合は、コールバックURLがhttp://localhost:8788/callbackである、同一設定の2つ目のGitHub Appを作成するとよいでしょう。

2. KV名前空間を作成する

最短の方法 — ./scripts/setup.sh <your-github-login> は依存関係のインストール、名前空間の作成、wrangler.jsoncへの名前空間idと許可リストの書き込みを一度に行います。その後はステップ3に進んでください。

手動で行う場合：

cd github-mcp-gateway
npm ci
npx wrangler kv namespace create OAUTH_KV

返されたidをwrangler.jsoncのkv_namespaces[0].idにコピーし、コミットされている値を置き換えてください。その値はプレースホルダーではなく、メンテナが実際に使用している名前空間です — このリポジトリはテンプレートであると同時に実行中のデプロイでもあるため、チェックインされた設定は本物です。これは識別子であり、認証情報ではありません。フォークに何も付与するものではありませんが、そのままにしておくと、あなたのWorkerはアカウントが到達できない名前空間に対して起動することになります。

3. シークレットと許可リスト変数を設定する

npx wrangler secret put GITHUB_APP_CLIENT_ID
npx wrangler secret put GITHUB_APP_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

ALLOWED_GITHUB_LOGINSはシークレットではなく通常の変数です — wrangler.jsoncのトップレベルの"vars"ブロックに追加してください：

"vars": {
  "ALLOWED_GITHUB_LOGINS": "your-github-login"
}

これはOAuthコールバックでチェックされる多層防御の許可リストです。自分のアカウントに対するGitHubの同意画面を完了できるのはあなただけですが、これにより「認証できる人なら誰でも」という暗黙のゲートではなく、コード上で明示的なゲートになります。未設定または空の値は全員を拒否します — フェイルクローズドなので、手順の見落としはサーバーを開放するのではなく、自分を締め出すことになります。

4. デプロイする

npx wrangler deploy

5. クライアントを接続する

任意のMCPクライアントを次のURLに向けてください：

https://github-mcp-gateway.<your-subdomain>.workers.dev/mcp

• Claude Code: claude mcp add --transport http github-mcp-gateway <url>

• Claude.ai / Cowork: そのURLでカスタムMCPコネクタを追加します。

クライアントはDCRを介して自己登録し、このサーバーの同意画面、次にGitHubの同意画面へあなたをリダイレクトし、ツールが利用可能な状態で戻ってきます。

ローカル開発

cp .dev.vars.example .dev.vars   # fill in the *local* GitHub App's credentials
npx wrangler dev

wrangler devはhttp://localhost:8788で提供されます — MCPクライアント（例：MCP Inspector）をhttp://localhost:8788/mcpに向けてください。

トークンのライフサイクル

互いに独立した2つのトークン関係が、異なる時間軸で存在します：

1. Cowork ↔ このWorker。 workers-oauth-providerによって発行される標準的なOAuth 2.1アクセス／リフレッシュトークン。CoworkがMCP仕様に従ってこれらを自動的に更新します — ここで管理するものはありません。

2. このWorker ↔ GitHub。 8時間のアクセストークン＋6か月のリフレッシュトークン。src/github-client.tsはGitHub API呼び出しのたびに有効期限をチェックし、期限切れの5分前になると透過的に更新します。ローテーションされたペアはOAUTH_KVのgithub:tokens:{your-login}に永続化されます。これは意図的にworkers-oauth-providerのtokenExchangeCallbackフックには配線されていません — その仕組みには上流の既知のバグがあり（更新後にpropsが陳腐化し、再認証ループを引き起こした；参考文献を参照）— そのため、代わりに推論とテストがより簡単なツールレイヤーで直接処理されています。

GitHubのリフレッシュトークン自体が期限切れになった場合（6か月以上未使用）や、アプリのアクセスを取り消した場合、次のツール呼び出しは、Coworkで切断して再接続するよう指示する明確なReauthorizationRequiredErrorメッセージとともに失敗します。ここに静かな失敗モードはありません — バックグラウンドで静かに機能するか、何をすべきかを正確に伝えるかのどちらかです。

ツール

すべてのリストツールは、ページネーション用にper_pageとpageを受け付けます。

github_merge_pull_requestとgithub_delete_fileは破壊的な2つの操作です — 一度呼び出されると、ツール自体からは元に戻せません。クライアントはどちらかを呼び出す前に、あなたに確認する必要があります。

github_update_repo (description、homepage、topics)を使用するには、GitHub AppにAdministrationリポジトリ権限が必要です。現在の設定(Contents/Issues/PRs/Metadata)のアプリにはこの権限が含まれていません — App設定で権限を追加してインストールを再承認し、このツールを有効にするか、代わりにgh CLIでそれらの編集を行ってください。

設計上の制限(意図的なもの)

採用する前に読んでください — これらは設計上の決定であり、欠落ではありません。

デプロイメントごとに1人のオペレーター

このサーバーは設計上シングルテナントです。ALLOWED_GITHUB_LOGINSはOAuthコールバックを制御し、カンマ区切りのリストを受け付け、トークンストレージもログインごとにキー設定されています(github:tokens:{login})が、意図された構成は1人につき1デプロイメントです。

これは脅威モデルに基づく決定です。共有デプロイメントでは、1人のオペレーターのKV名前空間に他の人のGitHubリフレッシュトークン — リポジトリへの書き込みアクセス権を持つ6ヶ月間有効な認証情報 — が保持されることになります。これにより、オペレーターは、そのような保証のないインフラ上で、侵害通知義務を負う認証情報の管理者となります。セルフホスティングはすべての認証情報を、それが属するアカウント内に保持します。これがこの設計のまさに要点です。

つまり:フォークして自分で実行してください。 まさにそのための./scripts/setup.shがあります。セットアップはおよそ10分で、Cloudflareの無料プランで個人利用はまかなえます。

リポジトリのスコープはインストール時に設定され、このサーバーでは設定されません

これは従来のOAuth AppではなくGitHub Appであるため、このアプリ経由でアクセスできるリポジトリは、GitHub自身のインストール画面で選択したものだけです。このサーバーはその範囲を広げることはできず、どのツール呼び出しもその外には到達できません。スコープを変更するには、インストールを変更してください。

github_update_repoにはアプリに同梱されていない権限が必要

Administrationリポジトリ権限が必要です。App設定で権限を追加してインストールを再承認するか、gh CLIを使用してdescriptionとトピックを編集してください。

ホステッドサービスではない

クライアントの接続先となる公開インスタンスは存在しません。このリポジトリ内で参照されているworkers.dev URL(deploy.yml、SECURITY.md、またはDockerfileヘッダー内)は、すべてメンテナ自身のデプロイメントであり、その許可リストはあなたを拒否します。これはあなたが実行するソースコードであり、サインアップして利用するサービスではありません。

セキュリティノート / このビルドで対処済みの既知の上流問題

• CSRF、stateリプレイ、セッション固定 — src/oauth/workers-oauth-utils.tsで、同意フォーム上のCSRFトークン+クッキーのペア、使い捨てのKVベースのstate(有効期限10分)、およびGitHubコールバックを完了するブラウザーがフローを開始したブラウザーと同じであることを証明するセッション結合クッキー(stateトークンのSHA-256ハッシュ)によって処理されています。

• workers-oauth-provider Issue #133 — オーディエンス検証におけるパス処理のバグにより、一部のバージョンでは特にClaude.ai/Cowork接続が壊れていました。このビルドでは、文書化された回避策として、リソースインジケーターにパスコンポーネントを追加しないようにしています(/mcpルートと/sseルートは、より長いパスの下にネストするのではなく、apiHandlersのルートに登録されています)。Coworkの最初の接続試行がトークン交換ステップで失敗する場合、上流で最初に確認すべき項目はこれです。

• Issue #108 (RFC 8707パス付きオーディエンス検証) — 上記と同じ根本原因。緩和策も同じです。

• Issue #29 (本番環境でのリダイレクトURI不一致) — DCRで登録されたリダイレクトURIは、一部のクライアントで、本番環境とwrangler devでは動作が異なることが報告されています。Coworkのリダイレクトがデプロイ後にのみ失敗する場合(ローカルでは動作する場合)、これが既知の原因候補です。

• __Host-クッキープレフィックスを全体で使用 — (ブラウザーによって強制される)このプレフィックスにより、クッキーがスコープを広げ得るDomain属性なしに、HTTPS経由でこの正確なオリジンによってのみ設定され得ることが保証されます。

参考文献

• Cloudflare Agents — リモートMCPサーバーを構築する

• cloudflare/workers-oauth-provider — このサーバーが依存するダウンストリームのOAuth 2.1実装

• GitHub Docs — ユーザーアクセストークンの更新

• workers-oauth-provider Issue #133 (Claude.ai接続失敗)およびIssue #108 (RFC 8707パスオーディエンスのバグ)