GitHub Webhook MCP

github-webhook-mcp

Stdio MCP proxy that bridges local MCP clients (Claude Desktop, Claude Code, Codex, etc.) to a remote github-webhook-mcp Cloudflare Worker. The Worker receives GitHub webhook deliveries, persists them in a per-tenant Durable Object (SQLite), and exposes them through MCP tools and a real-time WebSocket stream.

This package is the client-side proxy only. Webhook ingestion, tenant routing, persistence, and the MCP server itself run on the Worker. See the main repository for architecture and self-hosting instructions.

Breaking change: MCP protocol revision 2026-07-28

From this release the Worker serves MCP protocol revision 2026-07-28 only, with no compatibility lane for the previous revision.

• Proxy versions older than this release stop working. They open a session with initialize, which the Worker no longer answers. The failure is quiet: the proxy does not crash, it returns the protocol error as tool output text.
• Real-time channel notifications keep arriving, which hides the breakage. The /events WebSocket stream is not MCP and is unaffected, so a stale proxy still pushes event summaries while every tool call — including mark_processed — fails. The pending queue stops being cleared even though notifications look healthy.
• Restart the MCP client to pick up the new proxy. npx resolves @latest at process start, so an already-running Claude Desktop, Claude Code, or Codex keeps the copy it launched with however new the published version is. Quit it fully and reopen.
• Pinning the proxy version leaves you stuck. If your MCP client config pins a version older than this release, restarting does not help; remove the pin (or move it forward) first.

The proxy's two protocol faces are independent: it still speaks the 2025-era MCP revision to your client over stdio. Only the face toward the Worker moved.

What this proxy does

• Speaks stdio MCP locally to your client.
• Forwards tools/call to the Worker's Streamable HTTP MCP endpoint (/mcp).
• Optionally maintains a WebSocket connection to the Worker's /events endpoint and re-emits incoming webhook events as Claude Code claude/channel notifications (real-time push, no polling).
• Handles Worker-hosted web OAuth against the Worker. The proxy identifies itself with an OAuth Client ID Metadata Document served by the Worker, and falls back to Dynamic Client Registration (RFC 7591) against Workers that do not advertise support. No localhost callback port is used: GitHub's redirect_uri is pinned to the Worker itself, so the flow works reliably across process restarts and concurrent client instances.
• Caches access and refresh tokens under ~/.github-webhook-mcp/ (mode 0600) and refreshes them silently before expiry. On invalid_grant during refresh, the proxy re-reads the tokens file to adopt any rotation performed by a sibling process before falling back to a full re-authorization.

Requirements

• Node.js >= 18
• A reachable github-webhook-mcp Worker (the public preview default is https://github-webhook.smgjp.com; you can also point at your own deployment)
• A web browser (used once to sign in on GitHub via the authorize URL the proxy prints — can be on a different machine from where the MCP client runs)
• A GitHub App installed on the accounts/organizations whose events you want to receive (the Worker resolves your accessible installations automatically after OAuth)

Install / Run

The proxy is published to npm and exposes a github-webhook-mcp binary.

Run directly with npx (no global install required):

npx github-webhook-mcp

Or install globally:

npm install -g github-webhook-mcp

github-webhook-mcp

On first run the proxy prints an authorize URL to stderr and tries to open it in your default browser:

[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)...

Sign in on GitHub (2FA works as usual), approve access, and close the tab when the "Authorization complete" page appears. Tokens are stored under ~/.github-webhook-mcp/ and refreshed automatically before expiry.

Migrating from v0.10.x / v0.11.0. v0.10.x used a browser-based localhost callback flow; v0.11.0 used a GitHub device code flow. On first run with v0.11.1+, the proxy treats any tokens file whose flow marker does not match the new web flow as inactive and transparently starts the new authorization. One-time re-authentication is required; the legacy file is left in place but ignored.

Configure the Callback URL on self-hosted GitHub Apps. If you self-host the Worker with your own GitHub App, register https:// /oauth/callback as the Callback URL. Without it, the Worker's /oauth/callback step fails with "Authorization failed" because GitHub will reject the redirect. Device Flow is not used and can stay off. See the self-hosting guide for step-by-step instructions.

Updating

npx resolves the package version once, at process start — including when the client config pins @latest. A client that is already running keeps the version it launched with, so a new npm release does not reach it until that process is replaced: restart the MCP client (Claude Desktop, Claude Code, Codex) to pick up a new version. The restart is what moves the client onto the new version.

This matters most for releases that change the tool schemas the proxy advertises, because those schemas are served from the proxy's own code rather than fetched from the Worker — until the process restarts, the client keeps seeing the old tool definitions.

Verify what the registry holds with --prefer-online. The npm CLI caches registry metadata, so a bare npm view can report the previous version shortly after a publish:

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

Client configuration

Claude Desktop / Claude Code

Add the server to your MCP client configuration. Example for Claude Desktop (claude_desktop_config.json):

{

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

To target a self-hosted Worker, set the WEBHOOK_WORKER_URL environment variable:

{

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

alwaysLoad: true requires Claude Code v2.1.121 or later. It exempts this server's tools from tool-search deferral so they remain immediately callable every turn (recommended because the server is invoked every turn via the UserPromptSubmit hook).

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 disables the WebSocket real-time channel. Set it to 0 for clients that do not support claude/channel notifications (Claude Desktop, Codex). Leave it at the default to enable real-time push for Claude Code.

Real-time channel notifications (Claude Code only)

When WEBHOOK_CHANNEL is enabled (the default), the proxy declares the claude/channel experimental capability and re-emits new webhook events as channel notifications. To make them visible in a Claude Code session, load the channel:

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

Notifications are one-way: they include event type, repo, action, title, sender, and URL. There is no reply tool.

Configuration

OAuth client registration and tokens are stored in:

• ~/.github-webhook-mcp/oauth-client.json (dynamic client registration; only written when the Worker does not support Client ID Metadata Documents)
• ~/.github-webhook-mcp/oauth-tokens.json (access + refresh tokens, and the client_id they were issued to)

Delete these files to force a fresh authorization flow.

Note on the default Worker URL. https://github-webhook.smgjp.com is a preview instance offered for evaluation. It has no SLA and may change or stop without notice. For production use, deploy your own Worker (see the main repository's installation guide) and set WEBHOOK_WORKER_URL accordingly.

Passive observer connections

Set WEBHOOK_OBSERVER=1 on a dedicated bridge process to observe pending status without starting authentication UI. Authenticate using a separate normal CLI process first. Observer calls read the saved token file once per credential acquisition, so an external login can recover the connection on the next call. Missing, malformed, expired, or rejected credentials return a tool error with isError: true and matching JSON text / structuredContent:

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

Observer mode does not register a client, refresh tokens, open a browser, or start OAuth polling. A saved token with no expiry is accepted until rejected by the server. Authentication failures stop background WebSocket reconnection; after external login, the next successful tool call restarts it. WEBHOOK_CHANNEL still controls channel notifications, and get_event remains available.

Detect the contract using tools/list: only the observer get_pending_status entry advertises _meta: {"io.github.Liplus-Project/github-webhook-mcp/pending-status-observer": 1}. Its result preserves the Worker's raw JSON text and any structuredContent, including nonzero counts:

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

types maps event names to counts. latest_received_at is a timestamp string or null, and covers the latest pending event, not the full history. Status reads do not consume events or call mark_processed. Authentication and network failures are errors, not zero counts. Normal mode does not advertise this metadata; its existing nonzero status hook decision JSON and zero-count raw response remain unchanged. Use a separate process for hook callers that need that normal behavior.

Tools exposed

All tools are read-only except mark_processed.

| get_webhook_events