github-mcp-proxy

A self-hosted GitHub MCP server running on Cloudflare Workers, designed for personal / small-team use with per-repository guardrails for AI agents.

Any MCP-capable agent (Claude, Codex, ChatGPT, Cursor, Cline, …) can be plugged in — with tight control over which repos it can touch and how.

Why

Generic GitHub tokens give an agent full account access. This server narrows that down:

• Per-repo permission levels — read / issues / full

• Branch protection — new branches must match a prefix (default claude/); main/master never writable

• Commit-message policy — Conventional Commits, validated server-side

• Label whitelist — allowedLabels per repo; the server never auto-creates labels on GitHub

• Forbidden paths — .github/workflows/** always blocked

• Audit trail — every write auto-appends Signed-off-by / Assisted-by trailers or a footer identifying the agent and model

Architecture

 MCP agent ──(Streamable HTTP + OAuth)──▶ Cloudflare Worker
                                              │
                                              ├── workers-oauth-provider  (OAuth 2.1 server to MCP clients)
                                              ├── GitHub OAuth            (OAuth client to github.com)
                                              ├── KV                      (session tokens)
                                              ├── Durable Object          (MCP agent state)
                                              └── Octokit                 (GitHub REST)

Config (ghmcp.config.ts) is bundled with the Worker at deploy time — no runtime KV reads, typechecked via satisfies.

Quick start

git clone <your-fork>
cd kz-github-mcp
npm install
cp ghmcp.config.sample.ts ghmcp.config.ts   # edit: repos you want to expose
cp wrangler.sample.jsonc wrangler.jsonc      # edit: KV id + worker name
cp .env.example .env                         # edit: for local dev only

Create a GitHub OAuth App (Homepage = https://<worker>.<subdomain>.workers.dev, Callback = /callback), then:

wrangler kv namespace create "OAUTH_KV"      # add the id to wrangler.jsonc
wrangler secret put GITHUB_CLIENT_ID
wrangler secret put GITHUB_CLIENT_SECRET
wrangler secret put COOKIE_ENCRYPTION_KEY    # openssl rand -hex 32
npm run deploy

Local development: same flow with a second OAuth App pointing at http://localhost:8788, credentials in .env, then npm run dev.

Continuous deployment (optional)

.github/workflows/deploy.yml deploys to Cloudflare on every push to main. Set two repo secrets in GitHub Settings → Secrets and variables → Actions:

The GitHub OAuth credentials (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY) live as Wrangler secrets on the Worker itself, not in GitHub Actions — you only need to set them once with wrangler secret put.

See docs/ARCHITECTURE.md for how it works, docs/CONFIG.md for every config field.

Connect an AI agent

Claude (claude.ai) — Settings → Connectors → Add custom connector → paste https://<worker>.<subdomain>.workers.dev/sse.

Claude Code / Codex / Cursor / Cline — add to the client's MCP config:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["mcp-remote", "https://<worker>.<subdomain>.workers.dev/sse"]
    }
  }
}

Any MCP host — point it at the same /sse endpoint. OAuth flow runs on first connect.

Tools

Prefixed with ghmcp_. Each declares a minimum permission level; the server denies calls below that.

Any tool can be disabled via disabledTools in the config.

Validation

npm run validate-config

Uses the gh CLI to confirm that every repo in ghmcp.config.ts exists and that every label in allowedLabels is present on GitHub. Runs automatically as a prebuild hook, so a typo fails npm run build.

License

Originally forked from cloudflare/ai/demos/remote-mcp-github-oauth. MIT-licensed.

This tool is MIT-licensed. — see LICENSE.