Github Webhook MCP

What github-webhook-mcp does

github-webhook-mcp connects GitHub webhook delivery with MCP-compatible AI clients. The GitHub Web App receives events for selected organizations, accounts, and repositories, while a Cloudflare Worker validates webhook signatures and passes accepted events to a Durable Object backed by SQLite.

Events remain available as pending notifications until they are marked processed. The MCP interface provides both lightweight summaries for triage and complete payload retrieval for detailed analysis. A separate event stream can notify connected clients in real time, while MCP tool calls provide polling and state management.

The design is useful for repository monitoring, pull request review, CI status checks, and workflows that need an assistant to inspect and acknowledge GitHub activity.

How it works

Install the GitHub Webhook MCP app on a GitHub organization or account, then select the repositories that should deliver events. The app handles webhook delivery; creating an additional repository webhook for the same endpoint can produce duplicate or malformed requests.

The Cloudflare Worker stores incoming events in a Durable Object. The local .mcpb bridge connects an MCP client to the Worker and proxies tool requests. Desktop and Codex clients use MCP polling through the bridge, while Claude Code CLI can receive channel notifications through its WebSocket connection. No local webhook listener or tunnel is needed.

Pending status and summary listing exclude workflow_run events with requested or in_progress actions by default. Passing include_intermediate: true includes those events. This filtering affects the status and list results before limits are applied; full retrieval, processing, delivery, and retention behavior are unchanged.

Setup and configuration

The runtime prerequisite is Node.js 18 or newer. Self-hosting also requires a Cloudflare account and deployment of the Worker. A preview instance and client-specific setup instructions are available through the project's installation guide, covering Claude Desktop, Claude Code CLI, Codex, and Cloudflare Workers deployment.

The bridge is launched with npx. A newly started process resolves the package version at startup, so restart the MCP client after updates. If the configuration pins an older bridge version, remove or advance that pin before restarting. The Worker and bridge must use compatible MCP protocol revisions.

Event cleanup runs from a daily Durable Object Alarm. PURGE_AFTER_DAYS controls retention for processed events and defaults to three days. UNPROCESSED_PURGE_AFTER_DAYS controls unprocessed events and defaults to 90 days. Both values are configured in worker/wrangler.toml; a value of 0 removes that class during the sweep. Processed events are also removed promptly when marked.

Tools and capabilities

• get_pending_status returns pending event counts grouped by type and accepts the optional intermediate-event filter.
• list_pending_events returns pending-event summaries without full webhook payloads. It uses the same optional filter as the status tool.
• get_event retrieves the complete payload for one event by ID.
• get_webhook_events retrieves complete payloads for all pending events.
• mark_processed acknowledges one event with event_id or a batch with event_ids.

A typical inspection flow checks counts, lists summaries to identify a relevant event, and then retrieves its full payload. After review, one or more IDs can be passed to mark_processed.

Limitations and notes

Retention is based on event age rather than storage volume. A high-volume tenant that never consumes events can still approach Cloudflare's 1 GB Durable Object limit before the unprocessed-event retention period expires.

The WebSocket event stream is separate from MCP tool calls. Real-time notifications may continue appearing even when an outdated bridge can no longer complete tool requests, including processing operations. Restart the client with a compatible bridge after protocol or package updates.

The bridge proxies event data to the Worker and does not store event data locally. Events are stored in Cloudflare Durable Object edge storage.