github-mcp-gateway MCP server
Commit Nov 14, 2026A self-hosted Cloudflare Worker gateway that provides authenticated GitHub access to MCP clients via OAuth 2.1.
Also known as mazze93/github-mcp-gateway
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- Apache-2.0
What is github-mcp-gateway MCP?
github-mcp-gateway is a self-hosted Cloudflare Worker gateway that provides authenticated GitHub access to MCP clients via OAuth 2.1.
Summary generated from the project's README
About github-mcp-gateway MCP server
Providing authenticated GitHub access to MCP clients through a self-hosted Cloudflare Worker is what github-mcp-gateway enables. Developers can connect tools like Claude Code or Claude.ai to their own GitHub repositories using a secure OAuth 2.1 handshake. Because you deploy your own instance using a GitHub App, you maintain full control over which specific repositories the server can access through GitHub's installation picker.
The gateway acts as a middle layer that manages two distinct authentication flows. It serves as an OAuth server to your MCP client and an OAuth client to GitHub. This architecture ensures that your GitHub access tokens remain hidden from the client. The system includes 24 specialized tools for managing repositories, issues, pull requests, file contents, and code searches. It also handles automatic token rotation, using 8-hour access tokens and 6-month refresh tokens to ensure connectivity remains active without manual intervention.
What you can do with it
- 1Automate repository administrationWith appropriate permissions, the server can update repository metadata like descriptions and topics.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
ALLOWED_GITHUB_LOGINS
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemazze93/github-mcp-gateway is public and reachablegithub.com/mazze93/github-mcp-gateway ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-13github.com/mazze93/github-mcp-gateway ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubgithub-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
| 24 tools | repos (7), issues (6), pull requests (5), file contents (3), code and issue search (2), CI checks (1) — every list tool paginated; every tool declares MCP read-only / destructive annotations |
| Real OAuth 2.1 | PKCE, Dynamic Client Registration, and Client ID Metadata Documents, via Cloudflare's own workers-oauth-provider |
| Tokens that renew themselves | 8-hour GitHub access tokens refreshed transparently against a 6-month refresh token; the MCP client never sees either |
| A hardened release | multi-arch toolchain image, non-root and distroless, signed keyless with cosign, published with SBOM and SLSA provenance |
| Tested against the real runtime | OAuth, token and tool tests on workerd via @cloudflare/vitest-pool-workers, not a Node polyfill, plus a post-deploy smoke test against the live gateway |
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).
| Field | Value |
|---|---|
| GitHub App name | github-mcp-gateway (must be globally unique — append your username if taken) |
| Homepage URL | https://github-mcp-gateway.<your-subdomain>.workers.dev |
| Callback URL | https://github-mcp-gateway.<your-subdomain>.workers.dev/callback |
| Webhook | Uncheck "Active" — this server doesn't use webhooks |
| Repository permissions → Contents | Read & write |
| Repository permissions → Issues | Read & write |
| Repository permissions → Pull requests | Read & write |
| Repository permissions → Metadata | Read (mandatory, auto-selected) |
| Where can this GitHub App be installed? | Only on this account |
After creating it:
- Note the Client ID at the top of the app's settings page.
- Click Generate a new client secret — copy it now, it's shown once.
- 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.
- 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:
- 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. - This Worker ↔ GitHub. An 8-hour access token + 6-month refresh
token.
src/github-client.tschecks expiry before every GitHub API call and refreshes transparently when within 5 minutes of expiry, persisting the rotated pair toOAUTH_KVundergithub:tokens:{your-login}. This is deliberately not wired throughworkers-oauth-provider'stokenExchangeCallbackhook — 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
| Module | Tools |
|---|---|
src/tools/repos.ts |
github_list_repos, github_get_repo, github_list_branches, github_list_commits, github_get_commit, github_update_repo |
src/tools/issues.ts |
github_list_issues, github_get_issue, github_create_issue, github_comment_on_issue, github_close_issue |
src/tools/pulls.ts |
github_list_pull_requests, github_get_pull_request, github_list_pull_request_files, github_create_pull_request, github_merge_pull_request |
src/tools/contents.ts |
github_get_file_contents, github_create_or_update_file, github_delete_file |
src/tools/search.ts |
github_search_code, github_search_issues |
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.tsvia 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-providerIssue #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/mcpand/sseroutes are registered at the root ofapiHandlers, 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 devfor 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 noDomainattribute 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-providerIssue #133 (Claude.ai connection failures) and Issue #108 (RFC 8707 path audience bug)
github-mcp-gateway MCP questions
What tools are provided by this server?
It provides 24 tools covering repositories, issues, pull requests, file contents, code/issue search, and CI checks.
How does the authentication work?
It uses a GitHub App user-to-server flow with OAuth 2.1, PKCE, and Dynamic Client Registration, allowing you to scope access to specific repositories.
Do I need to manually refresh my GitHub tokens?
No, the server handles token rotation automatically using 8-hour access tokens and 6-month refresh tokens.
Is this a shared service?
No, this is source code you deploy yourself to your own Cloudflare Workers account; there is no shared instance.