github-mcp-proxy

Ein selbst gehosteter GitHub-MCP-Server, der auf Cloudflare Workers läuft und für den persönlichen Gebrauch oder kleine Teams mit Repository-spezifischen Leitplanken für KI-Agenten konzipiert ist.

Jeder MCP-fähige Agent (Claude, Codex, ChatGPT, Cursor, Cline, …) kann eingebunden werden — mit strikter Kontrolle darüber, welche Repositories er anfassen darf und wie.

[!WARNING] Wenn Sie Sicherheit oder Stabilität benötigen, verwenden Sie den offiziellen GitHub-MCP-Server. Sie können den Code frei forken; Sicherheitsaspekte liegen nach dem Fork in Ihrer eigenen Verantwortung.

Warum

Generische GitHub-Token geben einem Agenten vollen Zugriff auf das Konto. Dieser Server schränkt dies ein:

• Repository-spezifische Berechtigungsstufen — read / issues / full

• Branch-Schutz — neue Branches müssen einem Präfix entsprechen (Standard claude/); main/master sind niemals beschreibbar

• Commit-Message-Richtlinie — Conventional Commits, serverseitig validiert

• Label-Whitelist — allowedLabels pro Repository; der Server erstellt niemals automatisch Labels auf GitHub

• Verbotene Pfade — .github/workflows/** sind immer blockiert

• Audit-Protokoll — bei jedem Schreibvorgang werden automatisch Signed-off-by / Assisted-by-Zusätze oder eine Fußzeile angehängt, die den Agenten und das Modell identifiziert

Related MCP server: Kontrol

Architektur

 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)

Die Konfiguration (ghmcp.config.ts) wird zum Zeitpunkt der Bereitstellung mit dem Worker gebündelt — keine Laufzeit-KV-Lesezugriffe, typgeprüft via satisfies.

Schnellstart

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

Erstellen Sie eine GitHub OAuth App (Homepage = https://<worker>.<subdomain>.workers.dev, Callback = /callback), dann:

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

Lokale Entwicklung: gleicher Ablauf mit einer zweiten OAuth-App, die auf http://localhost:8788 zeigt, Anmeldedaten in .env, dann npm run dev.

Kontinuierliche Bereitstellung (optional)

.github/workflows/deploy.yml stellt bei jedem Push auf main auf Cloudflare bereit. Setzen Sie zwei Repository-Secrets unter GitHub Settings → Secrets and variables → Actions:

Die GitHub OAuth-Anmeldedaten (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY) liegen als Wrangler-Secrets auf dem Worker selbst, nicht in GitHub Actions — Sie müssen sie nur einmal mit wrangler secret put setzen.

Siehe docs/ARCHITECTURE.md für die Funktionsweise und docs/CONFIG.md für jedes Konfigurationsfeld.

Einen KI-Agenten verbinden

Claude (claude.ai) — Einstellungen → Connectors → Benutzerdefinierten Connector hinzufügen → https://<worker>.<subdomain>.workers.dev/sse einfügen.

Claude Code / Codex / Cursor / Cline — zum MCP-Konfigurationsfile des Clients hinzufügen:

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

Jeder MCP-Host — verweisen Sie ihn auf denselben /sse-Endpunkt. Der OAuth-Ablauf erfolgt bei der ersten Verbindung.

Um dem Agenten beizubringen, wie er die Tools korrekt verwendet, fügen Sie SKILL.md in seinen System-Prompt / seine Projektanweisungen / sein Skill-Verzeichnis ein.

Tools

Präfix ghmcp_. Jedes Tool deklariert eine Mindestberechtigungsstufe; der Server verweigert Aufrufe unterhalb dieser Stufe.

Jedes Tool kann über disabledTools in der Konfiguration deaktiviert werden.

Validierung

npm run validate-config

Verwendet die gh CLI, um zu bestätigen, dass jedes Repository in ghmcp.config.ts existiert und dass jedes Label in allowedLabels auf GitHub vorhanden ist. Läuft automatisch als prebuild-Hook, sodass ein Tippfehler npm run build fehlschlagen lässt.

Lizenz

Ursprünglich geforkt von cloudflare/ai/demos/remote-mcp-github-oauth. MIT-lizenziert.

Dieses Tool steht unter der MIT-Lizenz. — siehe LICENSE.