github-webhook-mcp

github-webhook-mcp

ローカルの MCP クライアント（Claude Desktop、Claude Code、Codex など）と、リモートの github-webhook-mcp Cloudflare Worker を接続する、stdio MCP プロキシです。Worker は GitHub webhook の配信を受け取り、テナントごとの Durable Object（SQLite）に永続化して、MCP ツールとリアルタイムの WebSocket ストリームを通じて公開します。

このパッケージはクライアント側のプロキシのみを提供します。Webhook の取り込み、テナントのルーティング、永続化、MCP サーバー自体は Worker 上で動作します。アーキテクチャとセルフホストの手順については、メインリポジトリを参照してください。

破壊的変更：MCP プロトコルリビジョン 2026-07-28

このリリース以降、Worker が提供するのはMCP プロトコルリビジョン 2026-07-28 のみで、以前のリビジョンとの互換性はありません。

• このリリースより前のプロキシバージョンは動作しなくなります。 これらのプロキシは initialize でセッションを開始しますが、Worker は応答しなくなりました。エラーは目立ちません。プロキシはクラッシュせず、プロトコルエラーをツールの出力テキストとして返します。
• リアルタイムチャネルの通知は届き続けるため、問題に気づきにくくなります。 /events WebSocket ストリームは MCP ではなく、この変更の影響を受けません。そのため、古いプロキシでもイベントの概要は引き続き送信されますが、mark_processed を含むすべてのツール呼び出しは失敗します。通知が正常に見えていても、保留中のキューはクリアされなくなります。
• 新しいプロキシを読み込むには、MCP クライアントを再起動してください。 npx はプロセスの起動時に @latest を解決するため、すでに起動している Claude Desktop、Claude Code、Codex は、公開されているバージョンがどれだけ新しくても、起動時に読み込んだコピーを使い続けます。完全に終了してから、再度起動してください。
• プロキシのバージョンを固定していると、先に進めません。 MCP クライアントの設定で、このリリースより前のバージョンを固定している場合、再起動しても解決しません。まず固定を解除するか、新しいバージョンに変更してください。

このプロキシが使用する2つのプロトコル接続は独立しています。クライアントとは、引き続き stdio 経由で 2025 年当時の MCP リビジョンを使用します。変更されたのは Worker 側との接続のみです。

このプロキシの機能

• ローカルでは、クライアントと stdio MCP で通信します。
• tools/call を Worker の Streamable HTTP MCP エンドポイント（/mcp）に転送します。
• オプションで、Worker の /events エンドポイントに WebSocket 接続を維持し、受信した webhook イベントを Claude Code の claude/channel 通知として再送信します（ポーリングなしのリアルタイムプッシュ）。
• Worker 上の Web OAuth と Dynamic Client Registration（RFC 7591）を処理します。localhost のコールバックポートは使用しません。GitHub の redirect_uri は Worker 自体に固定されるため、プロセスの再起動や複数クライアントインスタンスの同時実行時も、フローは安定して動作します。
• アクセストークンとリフレッシュトークンを ~/.github-webhook-mcp/（モード 0600）にキャッシュし、有効期限前にサイレントで更新します。更新時に invalid_grant が発生した場合、トークンファイルを再読み込みして、完全な再認証に切り替える前に、別のプロセスが行ったトークンローテーションを取り込みます。

必要条件

• Node.js >= 18
• 接続可能な github-webhook-mcp Worker（公開プレビューのデフォルトは https://github-webhook.smgjp.com です。独自のデプロイ先を指定することもできます）
• Web ブラウザー（プロキシが表示する認可 URL を使って GitHub に一度サインインする際に使用します。MCP クライアントを実行するマシンとは別のマシンでもかまいません）
• イベントを受信するアカウントまたは組織にインストールされた GitHub App（OAuth 後、Worker がアクセス可能なインストールを自動的に特定します）

インストール／実行

プロキシは npm で公開されており、github-webhook-mcp バイナリを提供しています。

npx で直接実行できます（グローバルインストールは不要です）。

npx github-webhook-mcp

または、グローバルにインストールします。

npm install -g github-webhook-mcp
github-webhook-mcp

初回の実行時に、プロキシは認証 URL を stderr に出力し、既定のブラウザーで開こうとします。

[github-webhook-mcp] OAuth authorization required.
[github-webhook-mcp] Opening: https://github-webhook.smgjp.com/oauth/authorize?client_id=abc&state=xyz
[github-webhook-mcp] Approve in the browser window; the tab can be closed when done.
[github-webhook-mcp] Waiting for approval (state expires in 600s)...

GitHub にサインインし（2FA は通常どおり利用できます）、アクセスを承認して、「Authorization complete」ページが表示されたらタブを閉じます。トークンは ~/.github-webhook-mcp/ に保存され、有効期限が切れる前に自動更新されます。

v0.10.x／v0.11.0 からの移行。 v0.10.x ではブラウザー経由の localhost コールバックフローが使用され、v0.11.0 では GitHub デバイスコードフローが使用されていました。v0.11.1 以降で初めて実行すると、プロキシはフローマーカーが新しいウェブフローと一致しないトークンファイルを無効として扱い、新しい認証を自動的に開始します。一度だけ再認証が必要です。以前のファイルはそのまま残りますが、無視されます。

セルフホストの GitHub Apps でのコールバック URL の設定。 独自の GitHub App で Worker をセルフホストする場合は、https://<your-worker>/oauth/callback をコールバック URLとして登録してください。登録しないと GitHub にリダイレクトが拒否されるため、Worker の /oauth/callback の手順が「Authorization failed」で失敗します。デバイスフローは使用されないため、無効のままでかまいません。詳しい手順については、セルフホストガイドを参照してください。

更新

npx はプロセスの起動時に一度だけパッケージのバージョンを解決します。クライアント設定で @latest を指定している場合も同様です。すでに実行中のクライアントは起動時のバージョンを使い続けるため、新しい npm リリースが反映されるのは、そのプロセスを置き換えた後です。新しいバージョンを適用するには、MCP クライアント（Claude Desktop、 Claude Code、Codex）を再起動してください。 再起動すると、クライアントが新しいバージョンに切り替わります。

これは、プロキシが公開するツールスキーマを変更するリリースで特に重要です。これらのスキーマは Worker から取得されるのではなく、プロキシ自身のコードから提供されるため、プロセスを再起動するまでは、クライアントに以前のツール定義が表示され続けます。

--prefer-online を指定して、レジストリに登録されているバージョンを確認してください。npm CLI はレジストリのメタデータをキャッシュするため、公開直後は、オプションを付けずに npm view を実行すると、以前のバージョンが表示されることがあります。

npm view github-webhook-mcp version --prefer-online

クライアント設定

Claude Desktop／Claude Code

MCP クライアントの設定にサーバーを追加します。Claude Desktop の設定例（claude_desktop_config.json）：

{
  "mcpServers": {
    "github-webhook": {
      "command": "npx",
      "args": ["-y", "github-webhook-mcp"],
      "alwaysLoad": true
    }
  }
}

セルフホストの Worker を使用する場合は、WEBHOOK_WORKER_URL 環境変数を設定します。

{
  "mcpServers": {
    "github-webhook": {
      "command": "npx",
      "args": ["-y", "github-webhook-mcp"],
      "alwaysLoad": true,
      "env": {
        "WEBHOOK_WORKER_URL": "https://your-worker.example.workers.dev"
      }
    }
  }
}

alwaysLoad: true を使用するには、Claude Code v2.1.121 以降が必要です。この設定により、このサーバーのツールはツール検索の遅延読み込み対象から除外されるため、毎ターンすぐに呼び出せる状態になります（UserPromptSubmit フック経由で毎ターンこのサーバーが呼び出されるため、推奨されます）。

Codex（config.toml）

[mcp.github-webhook-mcp]
command = "npx"
args = ["-y", "github-webhook-mcp"]

[mcp.github-webhook-mcp.env]
WEBHOOK_WORKER_URL = "https://your-worker.example.workers.dev"
WEBHOOK_CHANNEL = "0"

WEBHOOK_CHANNEL=0 を設定すると、WebSocket リアルタイムチャネルが無効になります。claude/channel 通知に対応していないクライアント（Claude Desktop、Codex）では 0 に設定してください。Claude Code でリアルタイムプッシュを有効にする場合は、既定値のままにしてください。

リアルタイムチャネル通知（Claude Code のみ）

WEBHOOK_CHANNEL が有効な場合（既定）、プロキシは claude/channel の実験的機能を宣言し、新しい Webhook イベントをチャネル通知として再送信します。Claude Code のセッションに通知を表示するには、チャネルを読み込みます。

claude --dangerously-load-development-channels server:github-webhook-mcp

通知は一方向で、イベントの種類、リポジトリ、アクション、タイトル、送信者、URL が含まれます。返信用ツールはありません。

設定

変数	必須	デフォルト	説明
WEBHOOK_WORKER_URL	いいえ	https://github-webhook.smgjp.com	MCP エンドポイント、WebSocket ストリーム、OAuth メタデータを公開する Cloudflare Worker のベース URL です。
WEBHOOK_OBSERVER	いいえ	0（無効）	保存済みのアクセストークンを使って、生の保留ステータスを取得し、対話なしで認証するには、正確に 1 に設定します。
WEBHOOK_CHANNEL	いいえ	1（有効）	WebSocket 接続と claude/channel 通知を無効にするには、0 に設定します。

OAuth クライアント登録情報とトークンは次の場所に保存されます。

• ~/.github-webhook-mcp/oauth-client.json（動的なクライアント登録）
• ~/.github-webhook-mcp/oauth-tokens.json（アクセストークンとリフレッシュトークン）

これらのファイルを削除すると、新しい認証フローが開始されます。

デフォルトの Worker URL に関する注意。 https://github-webhook.smgjp.com は評価用に提供されるプレビューインスタンスです。SLA はなく、予告なく変更または停止される場合があります。本番環境では、独自の Worker をデプロイし（メインリポジトリのインストールガイドを参照）、WEBHOOK_WORKER_URL を適切に設定してください。

パッシブオブザーバー接続

専用のブリッジプロセスで WEBHOOK_OBSERVER=1 に設定すると、認証 UI を起動せずに保留ステータスを監視できます。まず、別の通常の CLI プロセスを使って認証してください。オブザーバー呼び出しでは、認証情報を取得するたびに保存済みのトークンファイルを読み取るため、外部ログイン後、次の呼び出しで接続を復旧できます。認証情報がない、不正な形式、期限切れ、または拒否された場合は、isError: true と、対応する JSON テキスト／structuredContent を含むツールエラーが返されます。

{"error":"auth_required","message":"Observer mode requires an existing valid token. Authenticate using a separate CLI process, then retry."}

オブザーバーモードでは、クライアントの登録、トークンの更新、ブラウザーの起動、OAuth ポーリングは行われません。有効期限のない保存済みトークンは、サーバーに拒否されるまで受け入れられます。認証に失敗すると、バックグラウンドの WebSocket 再接続は停止します。外部ログイン後、次にツール呼び出しが成功すると再接続が開始されます。WEBHOOK_CHANNEL は引き続きチャネル通知を制御し、get_event も引き続き利用できます。

tools/list を使って、次の契約を検出してください。オブザーバーの get_pending_status エントリーのみが _meta: {"io.github.Liplus-Project/github-webhook-mcp/pending-status-observer": 1} を公開します。その結果には、ゼロ以外の件数も含め、Worker の生の JSON テキストと structuredContent がそのまま保持されます。

{"pending_count":3,"types":{"issues":3},"latest_received_at":"2026-10-19T00:00:00Z"}

types はイベント名を件数に対応付けます。latest_received_at はタイムスタンプ文字列または null で、履歴全体ではなく、最新の保留中イベントを示します。ステータスの読み取りでは、イベントは消費されず、mark_processed も呼び出されません。認証エラーやネットワークエラーはエラーとして扱われ、件数ゼロにはなりません。通常モードではこのメタデータは公開されません。既存の、ゼロ以外のステータスフックの判定 JSON と、件数ゼロの生のレスポンスは変更されません。この通常の動作が必要なフック呼び出し元には、別のプロセスを使用してください。

公開されるツール

mark_processed を除き、すべてのツールは読み取り専用です。

ツール	説明
get_pending_status	保留中（未処理）の Webhook イベントの軽量スナップショットです。保留件数、最新の受信タイムスタンプ、イベントタイプを返します。詳細を取得する前の定期的なポーリングに使用してください。
list_pending_events	保留中のイベントの概要一覧です（limit：1〜100、デフォルトは 20）。メタデータ（id、type、action、repo、sender、number、title、url、received_at）のみを返し、ペイロード全体は含みません。
get_event	event_id で指定した単一の Webhook イベントのペイロード全体を返します。
get_webhook_events	ペイロード全体を含む保留中のイベントを返します。ポーリングには get_pending_status または list_pending_events を優先し、すべての情報が本当に必要な場合に限り、こちらを使用してください。
mark_processed	イベントを処理済みにして、保留中のクエリに表示されないようにします。1 件のイベントには event_id を、1 回の呼び出しでまとめて処理するバッチには event_ids（1〜100）を渡します。保留キューが無制限に増えないようにするため、必須です。

推奨されるポーリングフロー

1. get_pending_status() を定期的に（例：60 秒ごとに）ポーリングします。
2. pending_count > 0 の場合は、概要を取得するために list_pending_events() を呼び出します。
3. 完全なペイロードが必要なイベントに限り、get_event(event_id) を呼び出します。
4. イベントを処理した後に mark_processed を呼び出します — event_ids: [...] を指定すると、通常のケースであるイベントのバッチをまとめて処理したときに、セット全体を 1 回の呼び出しでクリアできます。

リアルタイムチャネル通知が有効な場合（Claude Code）、プロキシは Worker がイベントを受信するとすぐに概要をプッシュするため、ステップ 1 は省略できます。ただし、キューをクリアするには mark_processed を呼び出す必要があります。

イベントの保持

Worker は保存されたイベントを自動的に削除するため、Durable Object のストレージ容量は上限内に保たれます。Durable Object Alarm で時間ベースのクリーンアップが毎日実行され、自動的に再スケジュールされるため、mark_processed が一度も呼び出されなくてもクリーンアップが行われます。

イベントクラス	保持期間	Worker の環境変数	デフォルト
処理済み（mark_processed が呼び出されたもの）	保持期間を過ぎたイベントは削除されます	PURGE_AFTER_DAYS	3 日
未処理（未処理としてマークされたことがないもの）	保持期間を過ぎたイベントは削除されます	UNPROCESSED_PURGE_AFTER_DAYS	90 日

• 未処理イベントの保持期間が長いのは意図的です。未処理とはユーザーが未確認であることを意味するため、削除までの猶予は長く設定されています（3 日と 90 日の差は設計によるものです）。
• 処理済みイベントは、迅速に削除するため mark_processed の呼び出し時にもすぐに削除されます。Alarm によるクリーンアップは、イベントの消費を停止したテナントにも対応する保証となります。
• どちらの保持期間も Worker 側の設定（worker/wrangler.toml の [vars]）です。値を 0 に設定すると、クリーンアップ時に該当クラスのイベントが直ちに削除されます。これらの環境変数は Worker に設定し、このプロキシには設定しません。
• 既知の制限：保持期間で上限が設けられるのはイベントの 経過時間 であり、量 ではありません。イベント発生率が高く、イベントが一度も消費されないテナントは、90 日の保持期間が適用される前に Cloudflare の 1 GB-per-DO の上限に達する可能性があります。

認証フロー

1. 最初のツール呼び出し時（またはキャッシュ済みのトークンがある場合は起動時）に、プロキシは ${WEBHOOK_WORKER_URL}/.well-known/oauth-authorization-server から OAuth メタデータを取得します。
2. クライアントがキャッシュされていない場合は、Dynamic Client Registration（RFC 7591）を実行し、urn:ietf:params:oauth:grant-type:web_authorization_poll と refresh_token のグラントタイプに対応していることを宣言します（パブリッククライアントで、シークレットはありません。Worker 自体は GitHub との通信に独自の GITHUB_CLIENT_SECRET を使用します）。
3. ランダムな state を生成し、${WEBHOOK_WORKER_URL}/oauth/authorize?client_id=<cid>&state=<state> をデフォルトのブラウザーで開きます。Worker は保留中の state レコードを保存し、redirect_uri を Worker 自身の /oauth/callback に固定して、GitHub の標準 URL https://github.com/login/oauth/authorize に 302 リダイレクトします（localhost は使用しません）。
4. GitHub にサインインして承認します。GitHub は ${WEBHOOK_WORKER_URL}/oauth/callback?code=<code>&state=<state> にリダイレクトします。Worker は GitHub アクセストークンを（機密クライアントとして）取得し、GitHub プロフィールとインストール情報を取得して、該当するグラントに紐付けられた独自の不透明なアクセストークンとリフレッシュトークンのペアを発行します。ブラウザーのタブには「認証が完了しました」と表示されます。
5. その間、プロキシは同じ state を使って ${WEBHOOK_WORKER_URL}/oauth/token に grant_type=urn:ietf:params:oauth:grant-type:web_authorization_poll を指定してポーリングします。コールバックが完了するまでは authorization_pending を受け取り、完了後の次のポーリングで Worker が発行したトークンのペアを受け取ります。
6. Worker はアクセス可能な GitHub インストール（ユーザーアカウント、および GitHub App がインストールされている組織）を特定して OAuth セッションに紐付けます。そのため、これらすべてのテナントからのイベントが同じ MCP セッションに届きます。
7. 以降の呼び出しではアクセストークンを再利用し、有効期限の5分前にサイレント更新します。Worker から 401 が返された場合、または更新時に invalid_grant が発生した場合、プロキシはまずトークンファイルを再読み込みします（別のプロセスがすでにトークンをローテーションしている可能性があるため）。ディスク上に新しいリフレッシュトークンがない場合にのみ、新しい Web フローにフォールバックします。

どの時点でも localhost ポートをリッスンしません。このフローは、ヘッドレスホストでも複数の MCP クライアントインスタンス間でも同じように動作します。

トラブルシューティング

• 認証 URL がログに表示されない。 MCP プロセスの stderr ストリームを確認してください（Claude Code ではサーバーのログとして表示されます）。[github-webhook-mcp] OAuth authorization required. ブロックを探してください。
• OAuth state expired before approval. Re-run the client to retry. state トークンは約 10 分で期限切れになります。任意のツール呼び出しを再度実行して、フローをやり直してください。
• ブラウザーに「Authorization failed」（Worker 502）と表示される。 Worker が GitHub コードの交換を拒否しました。セルフホスト環境では、通常、GitHub App の Callback URL に https://<your-worker>/oauth/callback が含まれていないか、GITHUB_CLIENT_SECRET が未設定または誤っていることが原因です。
• Failed to reach worker. WEBHOOK_WORKER_URL が正しく、マシンから到達可能であることを確認してください。
• すべてのツール呼び出しでプロトコルエラーが返るが、チャネル通知は届く。 実行中のプロキシは、Worker が現在提供している 2026-07-28 のリビジョンより古いものです。MCP クライアントを再起動して、npx が現在のバージョンを取得するようにしてください。設定で古いバージョンを固定している場合は、先に固定バージョンを新しくしてください。このページ上部の破壊的変更に関する注記を参照してください。
• Authentication failed after retry. キャッシュされたトークンが拒否され、再認証にも失敗しました。~/.github-webhook-mcp/oauth-tokens.json を削除して、再試行してください。
• v0.10.x / v0.11.0 からのアップグレード。 既存のトークンファイルは無視され（フローマーカーが一致しないため）、次のツール呼び出し時に新しい Web フローの認証 URL が出力されます。手動でのクリーンアップは不要です。
• イベントが届かない。 GitHub App が対象のアカウント／組織にインストールされていること、および GitHub App の Advanced → Recent Deliveries ページで Webhook の配信が成功していることを確認してください。Worker が受信するのは、認証済みアカウントに紐付けられたインストールのイベントのみです。
• Worker からの 429。 テナントごとのイベントクォータ（既定値 10,000）を超過しています。mark_processed を使ってバックログを処理し、空き容量を確保してください。
• リアルタイム通知が Claude Code に表示されない。 WEBHOOK_CHANNEL が 0 に設定されていないこと、および Claude Code が --dangerously-load-development-channels server:github-webhook-mcp を指定して起動されていることを確認してください。
• 認証情報が古い。 ~/.github-webhook-mcp/oauth-tokens.json（必要に応じて oauth-client.json も）を削除して、再試行してください。

リンク

• ソースとアーキテクチャ：https://github.com/Liplus-Project/github-webhook-mcp
• Worker のセルフホスト： docs/installation.md
• 要件仕様：docs/0-requirements.md
• Issue トラッカー：https://github.com/Liplus-Project/github-webhook-mcp/issues

ライセンス

Apache-2.0。メインリポジトリの LICENSE ファイルと NOTICE ファイルを参照してください。