github-mcp-proxy

Un servidor MCP de GitHub autohospedado que se ejecuta en Cloudflare Workers, diseñado para uso personal o de equipos pequeños con barreras de seguridad por repositorio para agentes de IA.

Cualquier agente compatible con MCP (Claude, Codex, ChatGPT, Cursor, Cline, …) puede conectarse, con un control estricto sobre qué repositorios puede tocar y cómo.

[!WARNING] Si necesitas seguridad o estabilidad, utiliza el servidor MCP oficial de GitHub. Puedes hacer fork libremente; los problemas de seguridad son tu responsabilidad una vez realizado el fork.

Por qué

Los tokens genéricos de GitHub otorgan al agente acceso total a la cuenta. Este servidor limita eso:

• Niveles de permiso por repositorio — read / issues / full

• Protección de ramas — las nuevas ramas deben coincidir con un prefijo (por defecto claude/); main/master nunca son editables

• Política de mensajes de commit — Conventional Commits, validados en el lado del servidor

• Lista blanca de etiquetas — allowedLabels por repositorio; el servidor nunca crea etiquetas automáticamente en GitHub

• Rutas prohibidas — .github/workflows/** siempre bloqueado

• Registro de auditoría — cada escritura añade automáticamente trailers Signed-off-by / Assisted-by o un pie de página que identifica al agente y al modelo

Related MCP server: Kontrol

Arquitectura

 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)

La configuración (ghmcp.config.ts) se empaqueta con el Worker en el momento del despliegue; no hay lecturas de KV en tiempo de ejecución, validado mediante satisfies.

Inicio rápido

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

Crea una GitHub OAuth App (Página de inicio = https://<worker>.<subdomain>.workers.dev, Callback = /callback), luego:

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

Desarrollo local: mismo flujo con una segunda OAuth App apuntando a http://localhost:8788, credenciales en .env, luego npm run dev.

Despliegue continuo (opcional)

.github/workflows/deploy.yml despliega en Cloudflare en cada push a main. Configura dos secretos de repositorio en GitHub Settings → Secrets and variables → Actions:

Las credenciales de GitHub OAuth (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, COOKIE_ENCRYPTION_KEY) residen como secretos de Wrangler en el propio Worker, no en GitHub Actions; solo necesitas configurarlos una vez con wrangler secret put.

Consulta docs/ARCHITECTURE.md para saber cómo funciona, y docs/CONFIG.md para cada campo de configuración.

Conectar un agente de IA

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

Claude Code / Codex / Cursor / Cline — añade a la configuración MCP del cliente:

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

Cualquier host MCP — apúntalo al mismo endpoint /sse. El flujo de OAuth se ejecuta en la primera conexión.

Para enseñar al agente cómo usar las herramientas correctamente, incluye SKILL.md en su prompt del sistema / instrucciones del proyecto / directorio de habilidades.

Herramientas

Prefijadas con ghmcp_. Cada una declara un nivel de permiso mínimo; el servidor deniega las llamadas por debajo de ese nivel.

Cualquier herramienta puede desactivarse mediante disabledTools en la configuración.

Validación

npm run validate-config

Utiliza la CLI gh para confirmar que cada repositorio en ghmcp.config.ts existe y que cada etiqueta en allowedLabels está presente en GitHub. Se ejecuta automáticamente como un hook prebuild, por lo que un error tipográfico hace que falle npm run build.

Licencia

Originalmente derivado de cloudflare/ai/demos/remote-mcp-github-oauth. Bajo licencia MIT.

Esta herramienta está bajo licencia MIT. — ver LICENSE.