Skip to content

README.md

Latest commit

 

History

History
134 lines (97 loc) · 4 KB

README.md

File metadata and controls

134 lines (97 loc) · 4 KB

github-webhook-mcp

Real-time GitHub webhook notifications for Claude via Cloudflare Worker + Durable Object.

Architecture

GitHub ──POST──▶ Cloudflare Worker ──▶ Durable Object (SQLite)
                                           │
                                           ├── MCP tools (Streamable HTTP)
                                           ├── SSE real-time stream
                                           │
                          ┌────────────────┘
                          │
     Desktop / Codex: .mcpb local bridge ──▶ polling via MCP tools
     Claude Code CLI: .mcpb local bridge ──▶ SSE → channel notifications
  • Cloudflare Worker receives GitHub webhooks, verifies signatures, stores events in a Durable Object with SQLite.
  • Local MCP bridge (.mcpb) proxies tool calls to the Worker and optionally listens to SSE for real-time channel notifications.
  • No local webhook receiver or tunnel required.

Prerequisites

Component Required
Node.js 18+ MCP server
Cloudflare account Worker deployment (self-hosting)

Installation

Claude Desktop — Desktop Extension (.mcpb)

Download mcp-server.mcpb from Releases, then:

  1. Open Claude Desktop → Settings → Extensions → Install Extension...
  2. Select the .mcpb file
  3. Enter your Worker URL when prompted (e.g. https://github-webhook-mcp.example.workers.dev)

Claude Code CLI — npx

{
  "mcpServers": {
    "github-webhook-mcp": {
      "command": "npx",
      "args": ["github-webhook-mcp"],
      "env": {
        "WEBHOOK_WORKER_URL": "https://github-webhook-mcp.example.workers.dev",
        "WEBHOOK_CHANNEL": "1"
      }
    }
  }
}

Set WEBHOOK_CHANNEL=1 to enable real-time channel notifications (Claude Code CLI only).

Codex — config.toml

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

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

Self-Hosting the Worker

1. Deploy to Cloudflare

cd worker
npm install
npx wrangler deploy

2. Set the webhook secret

npx wrangler secret put GITHUB_WEBHOOK_SECRET

3. Configure the GitHub webhook

  • Payload URL: https://your-worker.workers.dev/webhooks/github
  • Content type: application/json
  • Secret: same value as the Cloudflare secret
  • Events: select the events you want to receive

4. Optional: Channel notifications

The local MCP bridge supports Claude Code's claude/channel capability. When enabled, new webhook events are pushed into your session via SSE in real-time.

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

MCP Tools

Tool Description
get_pending_status Lightweight snapshot of pending event counts by type
list_pending_events Summaries of pending events (no full payloads)
get_event Full payload for a single event by ID
get_webhook_events Full payloads for all pending events
mark_processed Mark an event as processed

Monorepo Structure

worker/       — Cloudflare Worker + Durable Objects
local-mcp/    — Local stdio MCP bridge (TypeScript, dev)
mcp-server/   — .mcpb package for Claude Desktop
shared/       — Shared types and utilities

Privacy Policy

Events are stored in a Cloudflare Durable Object (edge storage). The local MCP bridge proxies tool calls to the Worker and does not store event data locally.

Support

Related