Verbindet lokale MCP-Clients mit einem Remote Cloudflare Worker, um GitHub Webhook-Events in Echtzeit zu streamen und zu verwalten.
Auch bekannt als Liplus-Project/github-webhook-mcp
- Stars
- 0
- Tools
- 5
- Downloads, 30 Tage
- —
- Neueste Version
- 0.8.2
- Letzter Commit
- 30. Okt. 2026
- Lizenz
- Apache-2.0
Was ist github-webhook MCP?
github-webhook ist ein MCP server. Verbindet lokale MCP-Clients mit einem Remote Cloudflare Worker, um GitHub Webhook-Events in Echtzeit zu streamen und zu verwalten. Er stellt 5 Tools bereit, etwa get_pending_status, list_pending_events, get_event.
Zusammenfassung generiert aus dem README des Projekts
Über github-webhook MCP server
Dieser Proxy fungiert als Bridge zwischen lokalen MCP-Clients wie Claude Desktop, Claude Code oder Codex und einem Remote Cloudflare Worker. Er ermöglicht es Entwicklern, GitHub Webhook-Events in Echtzeit direkt in ihrer KI-Umgebung zu streamen und zu verwalten. Während der Proxy die lokale stdio-Kommunikation übernimmt, erfolgen die eigentliche Ingestion, das Routing und die Persistenz der Webhooks auf dem Remote Worker unter Verwendung eines pro Tenant zugewiesenen Durable Object mit SQLite.
User interagieren mit dem System über spezifische Tools wie get_pending_status, list_pending_events und get_event, um Webhook-Payloads zu inspizieren. Der Proxy verwaltet die OAuth-Authentifizierung über einen Webbrowser und kümmert sich automatisch um das Token-Refreshing, wobei die Credentials im Home-Verzeichnis des Users gespeichert werden. Für Claude Code User kann er Echtzeit-Push-Benachrichtigungen über die claude/channel Capability aktivieren, was sofortige Updates zu Repository-Aktionen liefert, ohne dass manuelles Polling nötig ist.
Was du damit machen kannst
- 1Echtzeit-Repository-Updates empfangenAktiviere Live-Benachrichtigungen, damit der KI-Client sofort alarmiert wird, wenn neue GitHub Webhooks eingehen.
Geschrieben aus dem README des Projekts. Jeder Use Case wurde gegen ein Zitat daraus geprüft.
So installierst du github-webhook MCP
Formate geprüft am 10. Nov. 2026Zu Cursor hinzufügenZu Goose hinzufügengithub-webhook MCP in Claude Code installieren
$ claude mcp add github-webhook-mcp -- npx -y github-webhook-mcpgithub-webhook MCP in Cursor installieren
~/.cursor/mcp.json
{
"mcpServers": {
"github-webhook-mcp": {
"command": "npx",
"args": [
"-y",
"github-webhook-mcp"
]
}
}
}github-webhook MCP in VS Code installieren
.vscode/mcp.json
{
"servers": {
"github-webhook-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"github-webhook-mcp"
]
}
}
}github-webhook MCP in VS Code CLI installieren
$ code --add-mcp '{"name":"github-webhook-mcp","type":"stdio","command":"npx","args":["-y","github-webhook-mcp"]}'github-webhook MCP in Claude Desktop installieren
claude_desktop_config.json
{
"mcpServers": {
"github-webhook-mcp": {
"command": "npx",
"args": [
"-y",
"github-webhook-mcp"
]
}
}
}github-webhook MCP in Codex installieren
$ codex mcp add github-webhook-mcp -- npx -y github-webhook-mcpgithub-webhook MCP in Codex config.toml installieren
~/.codex/config.toml
[mcp_servers.github-webhook-mcp] command = "npx" args = ["-y", "github-webhook-mcp"]
github-webhook MCP in Gemini CLI installieren
$ gemini mcp add -s user github-webhook-mcp npx -- -y github-webhook-mcpgithub-webhook MCP in Gemini settings.json installieren
~/.gemini/settings.json
{
"mcpServers": {
"github-webhook-mcp": {
"command": "npx",
"args": [
"-y",
"github-webhook-mcp"
]
}
}
}github-webhook MCP tools 5
Erkannt aus dem READMEget_pending_statuslist_pending_eventsget_eventget_webhook_eventsmark_processed
| get_pending_status | — | |
| list_pending_events | — | |
| get_event | — | |
| get_webhook_events | — | |
| mark_processed | — |
Konfiguration
WEBHOOK_CHANNELSet to '0' to disable SSE channel notifications (default: enabled)
WEBHOOK_WORKER_URLURL of your deployed Cloudflare Worker endpoint (default: https://github-webhook.smgjp.com)
| Name | Beschreibung | Typ |
|---|---|---|
| WEBHOOK_CHANNEL | Set to '0' to disable SSE channel notifications (default: enabled) | |
| WEBHOOK_WORKER_URL | URL of your deployed Cloudflare Worker endpoint (default: https://github-webhook.smgjp.com) |
Automatisierte Checks
Geluften am 13. Nov. 2026Vollständiger Bericht →Unsere automatisierten Checks bestanden. Das ist kein Security-Audit: Lies den Code und gib dem Server nur den minimal notwendigen Zugriff. Wie die Checks funktionieren
- Source Repository verknüpft und erreichbarBestanden
- Open Source Lizenz (OSI)Bestanden
- Commit oder Release im letzten JahrBestanden
- Package-Name ähnelt keinem populären PackageBestanden
- Remote Endpoint nutzt HTTPSNicht geprüft
- Destruktive Tools sind markiertBestanden
- Keine versteckten Anweisungen an das ModellBestanden
- Keine kritischen Advisories im Paket oder seinen AbhängigkeitenBestanden
README
Auf GitHub ansehengithub-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
/eventsWebSocket stream is not MCP and is unaffected, so a stale proxy still pushes event summaries while every tool call — includingmark_processed— fails. The pending queue stops being cleared even though notifications look healthy. - Restart the MCP client to pick up the new proxy.
npxresolves@latestat 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/callto the Worker's Streamable HTTP MCP endpoint (/mcp). - Optionally maintains a WebSocket connection to the Worker's
/eventsendpoint and re-emits incoming webhook events as Claude Codeclaude/channelnotifications (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_uriis 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/(mode0600) and refreshes them silently before expiry. Oninvalid_grantduring 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://<your-worker>/oauth/callbackas the Callback URL. Without it, the Worker's/oauth/callbackstep 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
| Variable | Required | Default | Description |
|---|---|---|---|
WEBHOOK_WORKER_URL |
No | https://github-webhook.smgjp.com |
Base URL of the Cloudflare Worker that exposes the MCP endpoint, the WebSocket stream, and OAuth metadata. |
WEBHOOK_OBSERVER |
No | 0 (disabled) |
Set exactly to 1 for raw pending status and noninteractive authentication using an existing saved access token. |
WEBHOOK_CHANNEL |
No | 1 (enabled) |
Set to 0 to disable the WebSocket connection and claude/channel notifications. |
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 theclient_idthey were issued to)
Delete these files to force a fresh authorization flow.
Note on the default Worker URL.
https://github-webhook.smgjp.comis 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 setWEBHOOK_WORKER_URLaccordingly.
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.
| Tool | Description |
|---|---|
get_pending_status |
Lightweight snapshot of pending (unprocessed) webhook events: pending count, latest received timestamp, and event types. Use this for periodic polling before requesting details. |
list_pending_events |
Summary list of pending events (limit: 1-100, default 20). Returns metadata only — id, type, action, repo, sender, number, title, url, received_at — without the full payload. |
get_event |
Full payload for a single webhook event by event_id. |
get_webhook_events |
Pending events with full payloads. Prefer get_pending_status or list_pending_events for polling and only fall back to this when you really need everything. |
mark_processed |
Mark events as processed so they no longer appear in pending queries. Pass event_id for one event, or event_ids (1-100) to clear a whole batch in a single call. Required to keep the pending queue from growing unbounded. |
Recommended polling flow
- Poll
get_pending_status()periodically (e.g. every 60 seconds). - If
pending_count > 0, calllist_pending_events()for summaries. - Call
get_event(event_id)only for events that need the full payload. - Call
mark_processedafter handling the events —event_ids: [...]clears the whole set in one call, which is the normal case when a batch of events was handled together.
If real-time channel notifications are enabled (Claude Code), step 1 can be skipped — the proxy will push event summaries as soon as the Worker receives them. You still need to call mark_processed to clear the queue.
Event retention
The Worker purges stored events automatically so Durable Object storage stays bounded. A time-based sweep runs on a Durable Object Alarm (daily) and reschedules itself, so cleanup happens even when mark_processed is never called.
| Event class | Retention window | Worker env var | Default |
|---|---|---|---|
Processed (mark_processed called) |
events older than the window are deleted | PURGE_AFTER_DAYS |
3 days |
| Unprocessed (never marked) | events older than the window are deleted | UNPROCESSED_PURGE_AFTER_DAYS |
90 days |
- The longer window for unprocessed events is intentional — unprocessed means user-unseen, so the margin before dropping is wide (the 3-day vs 90-day asymmetry is by design).
- Processed events are also purged immediately on
mark_processedfor promptness; the Alarm sweep is the guarantee that covers tenants that stop consuming. - Both windows are Worker-side configuration (
worker/wrangler.toml[vars]); set a value to0to purge that class immediately on sweep. These env vars live on the Worker, not in this proxy. - Known limitation: the windows bound event age, not volume. A high-rate, never-consumed tenant can still hit Cloudflare's 1 GB-per-DO ceiling before the 90-day window applies.
Authentication flow
- On first tool call (or on startup if cached tokens exist), the proxy discovers OAuth metadata at
${WEBHOOK_WORKER_URL}/.well-known/oauth-authorization-server. - It picks its client_id. If the metadata carries
client_id_metadata_document_supported: trueand an httpsissuer, the client_id is<issuer>/oauth/client-metadata.json— a Client ID Metadata Document the Worker serves for this proxy — and no registration request is made. Otherwise it performs Dynamic Client Registration (RFC 7591) if no client is cached, declaring support for theurn:ietf:params:oauth:grant-type:web_authorization_pollandrefresh_tokengrant types. Either way it is a public client with no secret — the Worker itself uses its ownGITHUB_CLIENT_SECRETto talk to GitHub. Refresh always presents the client_id the tokens were issued to, so tokens obtained through an earlier registration keep refreshing after the Worker gains CIMD support. - It generates a random
stateand opens${WEBHOOK_WORKER_URL}/oauth/authorize?client_id=<cid>&state=<state>in your default browser. The Worker stores a pending state record and 302-redirects to GitHub's standardhttps://github.com/login/oauth/authorize, withredirect_uripinned to the Worker's own/oauth/callback(no localhost). - You sign in on GitHub and approve. GitHub redirects back to
${WEBHOOK_WORKER_URL}/oauth/callback?code=<code>&state=<state>. The Worker exchanges the code for a GitHub access token (confidential client), fetches your GitHub profile + installations, and issues its own opaque access/refresh token pair bound to that grant. The browser tab shows "Authorization complete". - Meanwhile the proxy polls
${WEBHOOK_WORKER_URL}/oauth/tokenwithgrant_type=urn:ietf:params:oauth:grant-type:web_authorization_pollagainst the same state. It receivesauthorization_pendinguntil the callback completes, then receives the Worker-issued token pair on the next poll. - The Worker resolves your accessible GitHub installations (your user account plus any organizations where the GitHub App is installed) and binds them to the OAuth session, so events from any of those tenants surface through the same MCP session.
- Subsequent calls reuse the access token and silently refresh it five minutes before expiry. On
401from the Worker orinvalid_grantduring refresh, the proxy first re-reads its tokens file (in case a sibling process has already rotated) and only falls back to a fresh web flow when no newer refresh token is on disk.
Concurrent bridges for the same OS user, normalized Worker URL and real authentication directory share one web flow. Only its owner registers, opens a browser, polls and saves tokens; other bridges return the same pending URL and expiry, then validate the saved scope/generation before continuing. Tool calls keep the 15-second startup limit and do not wait for the 600-second approval window. Observer mode remains read-only; refresh recovery is unchanged.
The owner holds an exclusive listener on 127.0.0.1, on one port derived from that scope's hash. This is private coordination, while the OAuth callback remains on the Worker. Every IPC request requires a random capability from a restrictive ~/.github-webhook-mcp/web-auth-<scope>.json record. Neither OAuth credentials nor unauthorized URL/state metadata are returned over IPC. Owner exit releases the listener; expiry aborts and fences its writes. A healthy owner repairs a damaged record; a replacement cannot be deleted or overwritten by its predecessor. Unknown listeners, blocked loopback listening and hash-port collisions fail closed with a retryable coordination error, rather than opening another flow on a different port.
Existing global token/client files still lack issuer metadata; this does not provide general cross-Worker cache isolation.
Troubleshooting
OAuth coordination unavailable; retry the tool call.Another local service may occupy the scope-derived port, or local policy may block loopback listening. Retry after the conflicting service/flow ends. Do not delete credential files or expose the listener on another interface.- Authorize URL never appears in the log. Check the stderr stream of the MCP process (Claude Code surfaces it as the server's log). Look for the
[github-webhook-mcp] OAuth authorization required.block. OAuth state expired before approval. Re-run the client to retry.The state token expires after ~10 minutes. Trigger any tool call again to restart the flow.- Browser lands on "Authorization failed" (Worker 502). The Worker rejected the GitHub code exchange. On self-hosts this usually means the GitHub App's Callback URL does not include
https://<your-worker>/oauth/callback, orGITHUB_CLIENT_SECRETis missing / wrong. Failed to reach worker. Check thatWEBHOOK_WORKER_URLis correct and reachable from your machine.- Every tool call returns a protocol error, but channel notifications still arrive. The running proxy predates the 2026-07-28 revision the Worker now serves. Restart the MCP client so
npxfetches the current version; if your config pins an older version, move the pin forward first. See the breaking-change note at the top of this page. Authentication failed after retry. Cached tokens were rejected and re-authentication did not succeed. Remove~/.github-webhook-mcp/oauth-tokens.jsonand retry.- Upgrading from v0.10.x / v0.11.0. Existing tokens files are ignored (flow marker mismatch) and a fresh web-flow authorize URL is emitted on the next tool call. No manual cleanup is required.
- No events arriving. Confirm that the GitHub App is installed on the target account/organization and that webhook deliveries are succeeding on the GitHub App's Advanced → Recent Deliveries page. The Worker only sees events for installations linked to your authenticated account.
429from the Worker. The per-tenant event quota (default 10,000) has been exceeded. Process the backlog withmark_processedto free space.- Real-time notifications not showing in Claude Code. Make sure
WEBHOOK_CHANNELis not set to0and that Claude Code was launched with--dangerously-load-development-channels server:github-webhook-mcp. - Stale credentials. Remove
~/.github-webhook-mcp/oauth-tokens.json(and optionallyoauth-client.json) and retry.
Links
- Source and architecture: https://github.com/Liplus-Project/github-webhook-mcp
- Self-hosting the Worker: docs/installation.md
- Requirements spec: docs/0-requirements.md
- Issue tracker: https://github.com/Liplus-Project/github-webhook-mcp/issues
License
Apache-2.0. See the LICENSE and NOTICE files in the main repository.
github-webhook MCP Fragen
Wie füge ich github-webhook MCP zu Claude Code hinzu?
Führe claude mcp add github-webhook-mcp -- npx -y github-webhook-mcp in deinem Terminal aus. Füge --scope user hinzu, damit der Server in jedem Projekt verfügbar ist.
Wie füge ich github-webhook MCP zu Cursor hinzu?
Öffne ~/.cursor/mcp.json und füge den Server unter mcpServers hinzu, mit der Cursor-Config aus dem Installationsabschnitt oben.
Welche Tools bietet github-webhook MCP?
Er stellt 5 Tools bereit, darunter get_pending_status, list_pending_events, get_event, get_webhook_events, mark_processed.
Unterstützt dies Echtzeit-Benachrichtigungen?
Ja, es kann eine WebSocket-Verbindung aufrechterhalten, um eingehende Webhook-Events als Echtzeit-Benachrichtigungen für Claude Code auszugeben.
Wie wird die Authentifizierung gehandhabt?
Der Proxy nutzt Web OAuth gegenüber dem Worker und cached Access- sowie Refresh-Tokens lokal in ~/.github-webhook-mcp/.
Kann ich meine eigene Cloudflare Worker Deployment nutzen?
Ja, du kannst den Proxy auf deine eigene Deployment verweisen, indem du die Umgebungsvariable WEBHOOK_WORKER_URL setzt.