github-mcp-gateway

Ein Remote-MCP-Server, der jedem MCP-Client authentifizierten GitHub-Zugriff bietet — Repos, Issues, Pull Requests, Dateiinhalte und Suche — über einen echten OAuth-2.1-Handshake auf Cloudflare Workers.

Funktioniert mit Claude Code, Claude.ai / Cowork und jedem spezifikationskonformen MCP-Client. Die Authentifizierung ist ein User-to-Server-Flow einer GitHub App, sodass die Repos, die der Server erreichen kann, genau die sind, die du auf GitHubs eigenem Installationsbildschirm auswählst — nicht alles, was dein Konto sehen kann.

Das ist Quellcode, den du selbst betreibst, kein Dienst, für den du dich anmeldest. Es gibt keine gemeinsame Instanz. Du deployest deinen eigenen Worker mit deiner eigenen GitHub App, und deine Zugangsdaten verlassen nie dein Konto — siehe Design-Limits. Die Einrichtung besteht aus einem Skript und dauert etwa zehn Minuten:

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

Was du bekommst

Related MCP server: Cloudflare GitHub OAuth MCP Server

Warum es das gibt und wie es aufgebaut ist

Ein MCP-Client kann mit deinen Zugangsdaten nicht direkt mit der GitHub-API sprechen — er braucht etwas dazwischen, das (a) beweist, wer fragt, (b) ein echtes GitHub-Token hält und (c) Tool-Aufrufe in GitHub-API-Anfragen übersetzt. Dieser Worker ist diese mittlere Schicht und spielt zwei OAuth-Rollen gleichzeitig:

• OAuth-Client gegenüber GitHub (Upstream) — er leitet dich durch GitHubs eigenen Zustimmungsbildschirm und tauscht den resultierenden Code gegen ein Token.

• OAuth-Server gegenüber dem MCP-Client (Downstream) — der Client sieht dein GitHub-Token nie. Er erhält sein eigenes Token von diesem Worker, das nur auf diesen Worker beschränkt ist. @cloudflare/workers-oauth-provider (Cloudflares eigene Bibliothek) implementiert diese Downstream-Hälfte: OAuth 2.1, PKCE und Dynamic Client Registration (DCR) — gerade DCR ermöglicht es einem Client, sich bei der ersten Verbindung selbst zu registrieren, ohne dass du manuell Zugangsdaten für ihn erstellst.

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

Warum eine GitHub App statt einer klassischen OAuth App

Cloudflares eigene Vorlage verwendet eine klassische OAuth App, die einfacher ist, dir aber Alles-oder-nichts-Repo-Scope und ein Token gibt, das nie abläuft, es sei denn, du implementierst den Ablauf selbst. Dieser Build verwendet stattdessen eine GitHub App mit dem User-to-Server-Token-Flow:

• Pro-Repo-Scoping bei der Installation — du wählst genau aus, welche Repos dieser Server berühren darf (GitHubs eigener Installations-Picker), nicht „alles, was dieses Konto sehen kann.“

• Tokens, die tatsächlich ablaufen und sich selbst erneuern — wenn „Expire user authorization tokens“ aktiviert ist, gibt GitHub ein 8-Stunden-Zugriffstoken plus ein 6-Monate-Refresh-Token zurück, und die Verwendung des Refresh-Tokens erzeugt ein neues Paar aus beiden. Solange du diesen Server mindestens einmal alle 6 Monate nutzt, verfällt nichts und du musst nie manuell ein neues Token erzeugen.

Dieser Erneuerungszyklus wird von src/github-client.ts übernommen, unabhängig von Coworks eigener Sitzung mit diesem Worker — siehe Token-Lifecycle weiter unten.

1. GitHub App erstellen

Gehe zu github.com/settings/apps/new (persönliches Konto) oder github.com/organizations/<org>/settings/apps/new (Org-eigen — verwende dies, wenn du sie unter einer Org statt unter deinem persönlichen Konto haben möchtest).

Nach der Erstellung:

1. Notiere die Client ID oben auf der Einstellungsseite der App.

2. Klicke auf Generate a new client secret — kopiere es jetzt, es wird nur einmal angezeigt.

3. Unter Optional features findest du User-to-server token expiration und klickst auf Opt-in. Nur dadurch gibt es überhaupt Refresh-Tokens — überspringst du diesen Schritt, schlägt der Server im Callback-Schritt mit einer klaren Fehlermeldung fehl, die dich auffordert, zurückzukehren und das zu erledigen.

4. Gehe zu Install App (linke Seitenleiste) und installiere sie auf deinem Konto, wobei du Only select repositories wählst — wähle die Repos aus, die dieser Server erreichen soll (du kannst später über denselben Bildschirm weitere hinzufügen).

Du wirst eine zweite GitHub App benötigen, die identisch konfiguriert ist, aber mit der Callback-URL http://localhost:8788/callback, wenn du vor dem Deployen lokal mit wrangler dev iterieren möchtest.

2. Den KV-Namespace erstellen

Schnellster Weg — ./scripts/setup.sh <your-github-login> installiert die Abhängigkeiten, erstellt den Namespace und schreibt wrangler.jsonc mit deiner Namespace-ID und deiner Allowlist neu. Springe dann zu Schritt 3.

Manuell:

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

Kopiere die zurückgegebene id in wrangler.jsonc unter kv_namespaces[0].id und ersetze dabei den eingecheckten Wert. Dieser Wert ist der Live-Namespace des Maintainers, kein Platzhalter — dieses Repository ist sowohl ein laufendes Deployment als auch eine Vorlage, daher ist die eingecheckte Konfiguration real. Es handelt sich um eine Kennung, nicht um Zugangsdaten: Sie gibt einem Fork nichts, aber wenn du sie an Ort und Stelle lässt, startet dein Worker gegen einen Namespace, den dein Konto nicht erreichen kann.

3. Secrets und die Allowlist-Variable setzen

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 ist eine einfache Variable, kein Secret — füge sie in wrangler.jsonc unter einem Top-Level-Block "vars" hinzu:

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

Das ist eine Defense-in-Depth-Allowlist, die beim OAuth-Callback geprüft wird: Auch wenn nur du den GitHub-Zustimmungsbildschirm für dein eigenes Konto abschließen kannst, macht das die Zugriffskontrolle im Code explizit, statt sie implizit als „wer sich authentifizieren kann“ zu belassen. Ein nicht gesetzter oder leerer Wert verweigert allen den Zugriff — die Logik ist fail-closed, sodass ein übersprungener Schritt dich aussperrt, statt den Server zu öffnen.

4. Deployen

npx wrangler deploy

5. Einen Client verbinden

Richte einen beliebigen MCP-Client auf:

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

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

• Claude.ai / Cowork: füge einen benutzerdefinierten MCP-Connector mit dieser URL hinzu.

Der Client registriert sich selbst über DCR, leitet dich durch den Zustimmungsbildschirm dieses Servers und dann durch den von GitHub weiter und landet mit verfügbaren Tools wieder.

Lokale Entwicklung

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

wrangler dev läuft unter http://localhost:8788 — richte einen MCP-Client (z. B. den MCP Inspector) auf http://localhost:8788/mcp aus.

Token-Lifecycle

Es gibt zwei unabhängige Token-Beziehungen mit unterschiedlichen Zeitrahmen:

1. Cowork ↔ dieser Worker. Standard-OAuth-2.1-Access-/Refresh-Tokens, ausgestellt von workers-oauth-provider. Cowork erneuert diese selbst, automatisch, gemäß der MCP-Spezifikation — hier gibt es nichts zu verwalten.

2. Dieser Worker ↔ GitHub. Ein 8-Stunden-Zugriffstoken + 6-Monate-Refresh-Token. src/github-client.ts prüft vor jedem GitHub-API-Aufruf das Ablaufdatum und erneuert transparent, wenn weniger als 5 Minuten bis zum Ablauf verbleiben, wobei das rotierte Paar in OAUTH_KV unter github:tokens:{your-login} gespeichert wird. Das ist bewusst nicht über den tokenExchangeCallback-Hook von workers-oauth-provider verdrahtet — dieser Mechanismus hat einen offenen Upstream-Bug (Props, die nach einer Erneuerung veralteten, lösten Re-Auth-Schleifen aus; siehe Referenzen) — stattdessen wird es direkt in der Tool-Schicht behandelt, wo es einfacher zu durchdenken und zu testen ist.

Wenn das Refresh-Token von GitHub selbst abläuft (6+ Monate ungenutzt) oder du den Zugriff der App widerrufst, schlägt der nächste Tool-Aufruf mit einer klaren ReauthorizationRequiredError-Meldung fehl, die dich anweist, in Cowork die Verbindung zu trennen und neu zu verbinden. Es gibt hier keinen stillen Fehlermodus — entweder funktioniert es leise im Hintergrund, oder es sagt dir genau, was zu tun ist.

Tools

Alle Listen-Tools akzeptieren per_page und page für die Paginierung.

github_merge_pull_request und github_delete_file sind die beiden destruktiven Operationen — einmal aufgerufen, sind sie über das Tool selbst nicht umkehrbar. Der Client sollte dich vor dem Aufruf um Bestätigung bitten.

github_update_repo (description, homepage, topics) erfordert, dass die GitHub-App über die Repository-Berechtigung Administration verfügt. Die App in der derzeitigen Konfiguration (Contents/Issues/PRs/Metadata) enthält diese nicht — fügen Sie die Berechtigung in den App-Einstellungen hinzu und genehmigen Sie die Installation erneut, um dieses Tool zu aktivieren, oder nehmen Sie diese Änderungen stattdessen mit der gh-CLI vor.

Design-Grenzen (bewusst)

Lesen Sie dies, bevor Sie das Projekt übernehmen — das sind Entscheidungen, keine Lücken.

Ein Betreiber pro Deployment

Dieser Server ist absichtlich Single-tenant. ALLOWED_GITHUB_LOGINS steuert den OAuth-Callback; obwohl die Variable eine kommagetrennte Liste akzeptiert und die Tokenübertragung bereits pro Login geschlüsselt ist (github:token:serlogin), ist die vorgesehene Form ein Deployment pro Person.

Das ist eine Bedrohungsmodell-Entscheidung. Ein gemeinsam genutztes Deployment würde bedeuten, dass der KV-Namespace eines Betreibers GitHub-Refresh-Tokens anderer Personen enthält — Anmeldedaten mit sechsmonatiger Laufzeit und Schreibzugriff auf Repositories. Das macht den Betreiber zum Zugangsverwalter mit der Pflicht, Sicherheitsverletzungen zu melden — auf Infrastruktur, die solche Garantien nicht bietet. Beim Selbsthosting bleiben alle Zugangsdaten in dem Konto, zu dem sie gehören; genau darum geht es im Design.

Also: Forken Sie das Projekt und betreiben Sie ein eigenes Deployment. ./scripts/setup.sh existiert genau dafür. Die Einrichtung dauert ungefähr zehn Minuten, und das kostenlose Cloud