Skip to content

Installation

Jump to bottom
liplus-lin-lay edited this page Mar 31, 2026 · 2 revisions

Installation

Quick Start

The fastest way to try github-webhook-mcp is using the preview instance:

  1. Install the GitHub Webhook MCP app on your GitHub account or organization
  2. Configure your MCP client (see MCP Client Setup below):
    • Worker URL: https://github-webhook.smgjp.com
  3. Start receiving webhook notifications

Note: The preview instance at github-webhook.smgjp.com is provided for evaluation purposes. There is no SLA, and the instance may change or stop without notice. For production use, see Self-Hosting Guide.

MCP Client Setup

Prerequisite: Node.js 18+ is required (used to run the local MCP bridge).

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 Guide

Deploy your own Cloudflare Worker instance for full control over webhook processing and data.

Prerequisites

Requirement Purpose
Cloudflare account Worker, Durable Object, and KV hosting
GitHub account Repository fork and GitHub App creation

1. Fork the Repository

Fork the github-webhook-mcp repository to your own GitHub account.

2. Create a Project in Cloudflare Workers & Pages

Create a Worker from the Cloudflare dashboard and connect it to your GitHub repository:

  1. Log in to the Cloudflare dashboard
  2. Go to Workers & Pages → Create → Import a repository
  3. Connect your GitHub account and select your forked repository
  4. Configure the build settings:
Setting Value
Worker name github-webhook-mcp (must match the name in wrangler.toml)
Root directory worker (monorepo — specify the directory containing the Worker source)
Build command npm install && npx wrangler deploy
  1. Select Save and Deploy

Important: The Worker name must match the name field in wrangler.toml. A mismatch will cause the build to fail.

Once deployed, the Worker URL will be displayed (e.g. https://github-webhook-mcp.example.workers.dev). Use this URL in the following steps.

After connecting, pushes to the repository will trigger automatic deployments.

The deployment automatically creates:

  • WebhookMcpAgent Durable Object — MCP tool provider (per-tenant)
  • WebhookStore Durable Object — Event persistence (per-tenant)
  • TenantRegistry Durable Object — Tenant management (single instance)
  • SQLite migrations are applied automatically

3. Create a KV Namespace

Create a KV Namespace for storing OAuth tokens. You can use either the Cloudflare dashboard or the wrangler CLI.

Via dashboard:

  1. Workers & Pages → KV → Create a namespace
  2. Enter OAUTH_KV as the namespace name and create it
  3. Note the Namespace ID displayed after creation

Via wrangler CLI:

cd worker
npx wrangler kv namespace create OAUTH_KV

With either method, set the KV Namespace ID in wrangler.toml replacing PLACEHOLDER_KV_ID:

[[kv_namespaces]]
binding = "OAUTH_KV"
id = "<paste your KV Namespace ID here>"

Commit and push the change to trigger an automatic deployment with the KV binding.

4. Create and Configure a GitHub App

Go to GitHub Settings → Developer settings → GitHub Apps → New GitHub App:

Basic Settings

Setting Value
App name Any name (e.g. My Webhook MCP)
Homepage URL Worker URL or repository URL
Webhook URL https://<your-worker>/webhooks/github
Webhook secret A strong random string (use the same value in step 5)
Content type application/json (required)

OAuth Settings (Required for MCP Remote Connection)

Setting Value
Callback URL https://<your-worker>/oauth/callback

Generate and note the Client ID and Client secret (used in step 5).

Permissions

Set according to the events you want to receive:

Category Permission Purpose
Issues Read Issue events
Pull requests Read PR events
Contents Read Push events
Checks Read Check run events
Actions Read Workflow run events
Discussions Read Discussion events

Event Subscriptions

Check the events you want to monitor:

  • Issues / Issue comment
  • Pull request / Pull request review / Pull request review comment / Pull request review thread
  • Push
  • Check run / Workflow run
  • Discussion / Discussion comment

Installation

After creation, install the app on your account or organization and select which repositories to monitor.

Important: Do not create a separate repository webhook for the same endpoint. The GitHub App handles all webhook delivery — a repository webhook would cause duplicate or malformed requests.

5. Set Secrets

Register three secrets in Cloudflare. You can set them via the dashboard at Workers & Pages → Worker → Settings → Variables and Secrets, or via the wrangler CLI:

# GitHub App Webhook secret
npx wrangler secret put GITHUB_WEBHOOK_SECRET

# GitHub App OAuth Client ID
npx wrangler secret put GITHUB_CLIENT_ID

# GitHub App OAuth Client Secret
npx wrangler secret put GITHUB_CLIENT_SECRET

Enter the corresponding value when prompted.

6. Custom Domain (Optional)

To use a custom domain instead of the default *.workers.dev URL:

  1. In the Cloudflare dashboard, go to Workers & Pages → Worker → Settings → Domains & Routes
  2. Add your custom domain (e.g. github-webhook.example.com)
  3. Update the Webhook URL and Callback URL in your GitHub App settings to use the custom domain
  4. Update WEBHOOK_WORKER_URL in your MCP client configuration

7. WAF Rules (Recommended)

Setting up Cloudflare WAF security rules blocks malicious requests before they reach the Worker, reducing CPU billing.

GitHub IP Restriction

Restrict access to the webhook endpoint to GitHub's IP ranges:

  • Target path: /webhooks/github
  • Condition: (http.request.uri.path eq "/webhooks/github") and not (ip.src in { 140.82.112.0/20 185.199.108.0/22 192.30.252.0/22 143.55.64.0/20 })
  • Action: Block

Note: GitHub's IP ranges may change. Check the latest ranges at https://api.github.com/meta under the hooks field.

Rate Limiting

  • Webhooks: 300 req/min per IP (/webhooks/github)
  • API: 120 req/min per IP (/mcp, /events)

8. Channel Notifications (Optional)

The local MCP bridge supports Claude Code's claude/channel capability. When enabled, new webhook events are pushed to your session via SSE in real-time. This feature is available in Claude Code CLI only.

Set WEBHOOK_CHANNEL=1 in your MCP client configuration (see Claude Code CLI above), then load the channel:

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

Verifying the Deployment

After deployment, verify with:

  1. Webhook reception test: GitHub App settings → Advanced → Recent Deliveries to check delivery status
  2. MCP connection test: Call the get_pending_status tool from your MCP client and verify the response
  3. SSE test: curl -N https://<your-worker>/events to verify stream connectivity

Troubleshooting

Symptom Cause and Resolution
Webhook returns 403 GITHUB_WEBHOOK_SECRET doesn't match the GitHub App setting. Verify both values
Webhook returns 429 Per-tenant quota exceeded (default 10,000 events). Process old events with mark_processed
OAuth login fails Verify GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are correct. Check that the Callback URL matches
KV error occurs Verify the KV ID in wrangler.toml matches the output of wrangler kv namespace create
MCP tools not responding Check if the Worker is deployed using wrangler tail to view logs

GitHub | npm | Discussions

github-webhook-mcp

Clone this wiki locally