github-mcp-gateway

A remote MCP server that gives any MCP client authenticated GitHub access — repos, issues, pull requests, file contents, and search — over a real OAuth 2.1 handshake, on Cloudflare Workers.

Works with Claude Code, Claude.ai / Cowork, and any spec-compliant MCP client. Authentication is a GitHub App user-to-server flow, so the repos it can reach are the ones you tick on GitHub's own installation screen — not everything your account can see.

This is source you run, not a service you sign up for. There is no shared instance. You deploy your own Worker against your own GitHub App, and your credentials never leave your account — see Design limits. Setup is one script and about ten minutes:

git clone https://github.com/mazze93/github-mcp-gateway
cd github-mcp-gateway && ./scripts/setup.sh <your-github-login>

What you get

Related MCP server: Cloudflare GitHub OAuth MCP Server

Why this exists, and the shape of it

An MCP client can't talk to GitHub's API directly with your credentials — it needs something in between that (a) proves who's asking, (b) holds a real GitHub token, and (c) translates tool calls into GitHub API requests. This Worker is that middle layer, and it plays two OAuth roles at once:

• OAuth client to GitHub (upstream) — it sends you through GitHub's own consent screen and exchanges the resulting code for a token.

• OAuth server to the MCP client (downstream) — the client never sees your GitHub token. It gets its own token from this Worker, scoped to this Worker only. @cloudflare/workers-oauth-provider (Cloudflare's own library) implements that downstream half: OAuth 2.1, PKCE, and Dynamic Client Registration (DCR) — DCR specifically is what lets a client register itself on first connection without you manually creating credentials for it.

MCP client ──OAuth (DCR, PKCE)──▶ this Worker ──OAuth (GitHub App)──▶ GitHub
                                       │
                                       ▼
                               Workers KV (OAUTH_KV)
                           state · refresh tokens · approved clients

Why a GitHub App instead of a classic OAuth App

Cloudflare's own template uses a classic OAuth App, which is simpler but gives you all-or-nothing repo scope and a token that never expires unless you build expiry yourself. This build uses a GitHub App with the user-to-server token flow instead:

• Per-repo scoping at install time — you pick exactly which repos this server can touch (GitHub's own installation picker), not "everything this account can see."

• Tokens that actually expire and renew themselves — with "Expire user authorization tokens" turned on, GitHub hands back an 8-hour access token plus a 6-month refresh token, and using the refresh token mints a new pair of both. As long as you use this server at least once every 6 months, it never goes stale and you never have to manually mint a new token.

That refresh cycle is handled by src/github-client.ts, independently of Cowork's own session with this Worker — see Token lifecycle, below.

1. Create the GitHub App

Go to github.com/settings/apps/new (personal account) or github.com/organizations/<org>/settings/apps/new (org-owned — use this if you want it under an org rather than your personal account).

After creating it:

1. Note the Client ID at the top of the app's settings page.

2. Click Generate a new client secret — copy it now, it's shown once.

3. Under Optional features, find User-to-server token expiration and click Opt-in. This is what makes refresh tokens exist at all — skip it and the server will fail at the callback step with a clear error telling you to come back and do this.

4. Go to Install App (left sidebar) and install it on your account, choosing Only select repositories — pick the repos you want this server to reach (you can add more later from the same screen).

You'll want a second GitHub App, identically configured but with the callback URL http://localhost:8788/callback, if you plan to iterate with wrangler dev locally before deploying.

2. Create the KV namespace

Quickest path — ./scripts/setup.sh <your-github-login> installs dependencies, creates the namespace, and rewrites wrangler.jsonc with your namespace id and your allowlist. Then skip to step 3.

By hand:

cd github-mcp-gateway
npm ci
npx wrangler kv namespace create OAUTH_KV

Copy the returned id into wrangler.jsonc under kv_namespaces[0].id, replacing the committed value. That value is the maintainer's live namespace, not a placeholder — this repository is a running deployment as well as a template, so the checked-in config is real. It is an identifier, not a credential: it grants a fork nothing, but leaving it in place means your Worker starts against a namespace your account cannot reach.

3. Set secrets and the allowlist var

npx wrangler secret put GITHUB_APP_CLIENT_ID
npx wrangler secret put GITHUB_APP_CLIENT_SECRET
openssl rand -hex 32 | npx wrangler secret put COOKIE_ENCRYPTION_KEY

ALLOWED_GITHUB_LOGINS is a plain var, not a secret — add it to wrangler.jsonc under a top-level "vars" block:

"vars": {
  "ALLOWED_GITHUB_LOGINS": "your-github-login"
}

This is a defense-in-depth allowlist checked at the OAuth callback: even though only you can complete the GitHub consent screen for your own account, this makes the gate explicit in code rather than implicit in "whoever can authenticate." An unset or empty value denies everyone — it fails closed, so a missed step locks you out rather than opening the server up.

4. Deploy

npx wrangler deploy

5. Connect a client

Point any MCP client at:

https://github-mcp-gateway.<your-subdomain>.workers.dev/mcp

• Claude Code: claude mcp add --transport http github-mcp-gateway <url>

• Claude.ai / Cowork: add a custom MCP connector with that URL.

The client registers itself via DCR, redirects you through this server's consent screen, then GitHub's, and lands back with tools available.

Local development

cp .dev.vars.example .dev.vars   # fill in the *local* GitHub App's credentials
npx wrangler dev

wrangler dev serves at http://localhost:8788 — point an MCP client (e.g. the MCP Inspector) at http://localhost:8788/mcp.

Token lifecycle

Two independent token relationships exist, on different clocks:

1. Cowork ↔ this Worker. Standard OAuth 2.1 access/refresh tokens issued by workers-oauth-provider. Cowork refreshes these itself, automatically, per the MCP spec — nothing to manage here.

2. This Worker ↔ GitHub. An 8-hour access token + 6-month refresh token. src/github-client.ts checks expiry before every GitHub API call and refreshes transparently when within 5 minutes of expiry, persisting the rotated pair to OAUTH_KV under github:tokens:{your-login}. This is deliberately not wired through workers-oauth-provider's tokenExchangeCallback hook — that mechanism has an open upstream bug (props going stale after a refresh triggered re-auth loops; see References) — so it's handled directly in the tool layer instead, where it's simpler to reason about and test.

If GitHub's refresh token itself expires (unused for 6+ months) or you revoke the app's access, the next tool call fails with a clear ReauthorizationRequiredError message instructing you to disconnect and reconnect in Cowork. There's no silent failure mode here — either it works quietly in the background, or it tells you exactly what to do.

Tools

All list tools accept per_page and page for pagination.

github_merge_pull_request and github_delete_file are the two destructive operations — irreversible via the tool itself once called. The client should confirm with you before invoking either.

github_update_repo (description, homepage, topics) requires the GitHub App to have the Administration repository permission. The app as currently configured (Contents/Issues/PRs/Metadata) does not include it — add the permission in the App settings and re-approve the installation to enable this tool, or make those edits with the gh CLI instead.

Design limits (deliberate)

Read this before adopting — these are decisions, not gaps.

One operator per deployment

This server is single-tenant by design. ALLOWED_GITHUB_LOGINS gates the OAuth callback, and while it accepts a comma-separated list and token storage is already keyed per-login (github:tokens:{login}), the intended shape is one deployment per person.

That is a threat-model decision. A shared deployment would mean one operator's KV namespace holding other people's GitHub refresh tokens — six-month credentials with repository write access. That makes the operator a credential custodian with a breach-notification obligation, on infrastructure with no such guarantees. Self-hosting keeps every credential in the account it belongs to, which is the whole point of the design.

So: fork it and run your own. ./scripts/setup.sh exists for exactly that. Setup is roughly ten minutes, and the Cloudflare free tier covers personal use.

Repository scope is set at install time, not by this server

Because this is a GitHub App rather than a classic OAuth App, the repos reachable through it are the ones you select on GitHub's own installation screen. This server cannot widen that, and no tool call can reach outside it. To change scope, change the installation.

github_update_repo needs a permission the app does not ship with

It requires the Administration repository permission. Add it in the App settings and re-approve the installation, or use the gh CLI for description and topic edits.

Not a hosted service

There is no public instance to point a client at. Any workers.dev URL you find referenced in this repository (in deploy.yml, SECURITY.md, or the Dockerfile header) is the maintainer's own deployment, and its allowlist will reject you. This is source you run, not a service you sign up for.

Security notes / known upstream issues this build accounts for

• CSRF, state replay, session fixation — handled in src/oauth/workers-oauth-utils.ts via a CSRF token + cookie pair on the consent form, one-time-use KV-backed state (10 min TTL), and a session-binding cookie (SHA-256 hash of the state token) that proves the browser completing the GitHub callback is the same one that started the flow.

• workers-oauth-provider Issue #133 — a path-handling bug in audience validation has, in some versions, broken Claude.ai/Cowork connections specifically. This build avoids adding path components to any resource indicator (the /mcp and /sse routes are registered at the root of apiHandlers, not nested under a longer path) as the documented workaround. If Cowork's first connection attempt fails at the token exchange step, this is the first thing to check upstream.

• Issue #108 (RFC 8707 audience validation with paths) — same root cause as above; same mitigation.

• Issue #29 (redirect URI mismatch in production) — DCR-registered redirect URIs have been reported to behave differently in production vs. wrangler dev for some clients. If Cowork's redirect fails only after deploying (and works locally), this is the known suspect.

• __Host- cookie prefix used throughout — guarantees (browser- enforced) that a cookie could only have been set by this exact origin over HTTPS, with no Domain attribute that could widen its scope.

References

• Cloudflare Agents — Build a Remote MCP Server

• cloudflare/workers-oauth-provider — the downstream OAuth 2.1 implementation this depends on

• GitHub Docs — Refreshing user access tokens

• workers-oauth-provider Issue #133 (Claude.ai connection failures) and Issue #108 (RFC 8707 path audience bug)