GitHub

Gestiona repositorios de GitHub usando un token de acceso personal a través de la CLI o variables de entorno.

Documentación

GitHub MCP Server (Kosta's Version)

Un servidor de Model Context Protocol (MCP) que proporciona operaciones integrales con repositorios de GitHub — lectura y escritura — mediante una interfaz CLI sencilla. Diseñado para Claude Desktop y otros clientes MCP.

v3.1.0 — Combina la expansión de herramientas de escritura v3 con transporte HTTP Streamable (/mcp), estructura de migración OAuth, carga diferida de herramientas y opciones de salida estructurada de herramientas.

Características

Exploración de repositorios, lectura de archivos y búsqueda de código
Ciclo de vida completo de issues/PR (listar, ver, crear, actualizar, fusionar, revisores, etiquetas)
Historial de commits, diffs y comparación de ramas
Creación/actualización/eliminación de archivos mediante commits directos
Creación y eliminación de ramas
Releases, creación/fork de repositorios e información de usuario
Anotaciones de herramientas (readOnly, indicaciones destructivas) para una selección inteligente de herramientas por IA
Instrucciones del servidor para guiar el flujo de trabajo de la IA
Limitación de velocidad y manejo integral de errores

Instalación y Uso

Inicio Rápido (Recomendado)

# Run directly with npx (no installation needed)
GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta

# Idle auto-exit defaults to 5 minutes (prevents leaked stdio servers from piling up).
# Disable if you need an always-on process:
MCP_IDLE_TIMEOUT_MS=0 GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta

# Not recommended (token is visible via `ps` on the machine):
npx github-mcp-server-kosta --github-token YOUR_GITHUB_TOKEN

# Streamable HTTP mode (native /mcp endpoint)
GITHUB_TOKEN=your_token_here npx github-mcp-server-kosta --transport http --http-port 3000

Instalación Global

npm install -g github-mcp-server-kosta
GITHUB_TOKEN=your_token_here github-mcp-server-kosta

Configuración del Token de GitHub

Ve a GitHub Settings → Developer settings → Personal access tokens
Genera un nuevo token (clásico) con estos alcances:
- repo (acceso completo para repos privados + operaciones de escritura)
- public_repo (para repositorios públicos, solo lectura)
- read:user (para información de usuario)
Usa el token con la CLI:

npx github-mcp-server-kosta --github-token ghp_your_token_here

Herramientas Disponibles

Operaciones de Repositorio

Herramienta	Descripción
`github_repo_info`	Obtiene metadatos del repositorio (estrellas, forks, lenguaje, etc.)
`github_list_contents`	Lista archivos/directorios en una ruta
`github_get_file_content`	Lee el contenido de un archivo (devuelve SHA para actualizaciones)
`github_get_readme`	Obtiene y decodifica el README
`github_search_code`	Busca código dentro de un repositorio
`github_list_repos`	Lista repositorios de un usuario/organización
`github_search_repos`	Busca repositorios a nivel global
`github_create_repo`	Crea un nuevo repositorio
`github_fork_repo`	Hace fork de un repositorio existente

Issues y Pull Requests

Herramienta	Descripción
`github_list_issues`	Lista issues (filtrar por estado, etiquetas, asignado)
`github_get_issue`	Obtiene detalles completos de un issue
`github_list_pulls`	Lista PRs (filtrar por estado, head, rama base)
`github_get_pull`	Obtiene detalles completos de un PR con estadísticas de diff
`github_create_issue`	Crea un nuevo issue
`github_update_issue`	Actualiza un issue (o PR) mediante la API de Issues (título/cuerpo/estado/etiquetas/asignados/hito)
`github_create_issue_comment`	Comenta en un issue o PR
`github_create_pull_request`	Crea un pull request
`github_update_pull_request`	Actualiza un pull request
`github_merge_pull_request`	Fusiona un pull request
`github_request_reviewers`	Solicita revisores para un pull request
`github_search_issues`	Busca issues y pull requests (sintaxis de búsqueda de GitHub)

Ramas, Commits e Historial

Herramienta	Descripción
`github_list_branches`	Lista todas las ramas
`github_list_commits`	Lista commits (filtrar por ruta, autor, fecha)
`github_get_commit`	Obtiene detalles de un commit con diff completo
`github_compare`	Compara dos ramas/etiquetas/commits
`github_create_branch`	Crea una nueva rama desde una ref
`github_delete_branch`	Elimina una rama

Releases y Usuarios

Herramienta	Descripción
`github_list_releases`	Lista releases con notas y recursos
`github_create_release`	Crea un release
`github_user_info`	Obtiene información de perfil de usuario/org

Operaciones de Archivos

Herramienta	Descripción
`github_create_or_update_file`	Crea o actualiza un archivo mediante commit
`github_delete_file`	Elimina un archivo mediante commit (requiere SHA)

Etiquetas

Herramienta	Descripción
`github_list_labels`	Lista etiquetas del repositorio
`github_create_label`	Crea una etiqueta de repositorio
`github_set_issue_labels`	Reemplaza todas las etiquetas en un issue/PR
`github_add_issue_labels`	Agrega etiquetas a un issue/PR
`github_remove_issue_label`	Elimina una etiqueta de un issue/PR
`github_add_labels`	Alias de compatibilidad: agrega etiquetas a issue/PR
`github_remove_label`	Alias de compatibilidad: elimina una sola etiqueta

Carga Diferida de Herramientas (Opcional)

Herramienta	Descripción
`github_tool_groups_list`	Lista grupos de herramientas y si están cargados
`github_tool_groups_load`	Carga grupos de herramientas y emite `notifications/tools/list_changed`
`github_tool_catalog_search`	Busca grupos/nombres de herramientas sin cargar todas las herramientas

Vía de Escape REST

Herramienta	Descripción
`github_rest_get`	GET genérico contra la API REST de GitHub (basado en ruta)
`github_rest_mutate`	Solicitud de escritura genérica (POST/PUT/PATCH/DELETE) protegida por `confirm: "CONFIRM_GITHUB_WRITE"`

Configuración del Cliente MCP

Para Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["github-mcp-server-kosta", "--github-token", "YOUR_GITHUB_TOKEN"]
    }
  }
}

Opciones de CLI

Options:
  -t, --github-token     GitHub access token for API requests (or set GITHUB_TOKEN / GITHUB_PERSONAL_ACCESS_TOKEN)
      --transport        Transport mode: stdio|http [default: stdio]
      --tool-mode        Tool listing mode: "full" or "lazy" [default: full]
      --preload-groups   Comma-separated tool group IDs to preload in lazy mode [default: core,search in lazy]
      --tool-schema-verbosity  Tool schema verbosity: "full" or "compact" [default: full]
      --tool-output      Tool output: text|structured|both [default: text]
      --tool-output-schema  Tool output schema: none|bootstrap|all_loose [default: none]
      --idle-timeout-ms  Exit after this many ms without receiving an MCP request (0 disables).
                         Defaults: stdio=0, http=300000 (unless MCP_IDLE_TIMEOUT_MS is set)
  -r, --rate-limit       Rate limit delay in ms between requests [default: 100]
      --http-host        HTTP bind host (http transport) [default: 127.0.0.1]
      --http-port        HTTP bind port (http transport; 0 chooses ephemeral) [default: 3000]
      --http-path        MCP endpoint path (http transport) [default: /mcp]
      --http-tls-key     TLS private key path (enables https when paired with --http-tls-cert)
      --http-tls-cert    TLS cert path (enables https when paired with --http-tls-key)
      --http-auth-token  Optional Bearer token required to access /mcp
      --http-allowed-origins  Comma-separated Origin allowlist (enforced only when Origin header is present)
      --http-allowed-hosts    Comma-separated Host allowlist (recommended when binding 0.0.0.0/::)
      --http-max-sessions     Maximum concurrent MCP sessions (DoS guard) [default: 50]
      --http-require-auth-on-public-bind  Refuse startup if binding non-localhost without --http-auth-token [default: false]
      --http-oauth-resource-metadata-url  Optional URL to advertise in WWW-Authenticate as resource_metadata
      --http-oauth-protected-resource-path  Optional local path to serve OAuth protected resource metadata JSON
      --http-oauth-authorization-server-issuer  Optional authorization server issuer included in metadata
      --http-oauth-scopes  Comma-separated scopes_supported included in metadata
      --http-oauth-cutover-path  Optional second MCP endpoint path for staged OAuth cutover (example: /mcp-oauth)
      --http-oauth-cutover-token  Bearer token required on cutover endpoint (falls back to --http-auth-token)
  -h, --help             Show help

Notas sobre la Carga Diferida de Herramientas

En --tool-mode lazy, el servidor solo expone herramientas de arranque más cualquier grupo precargado (por defecto: core,search).
Carga grupos adicionales en tiempo de ejecución usando github_tool_groups_load (p. ej., issues, pulls, rest).
El servidor anuncia tools.listChanged: true y emite notifications/tools/list_changed después de cargar los grupos, pero algunos clientes MCP pueden no actualizar automáticamente las listas de herramientas. Si tu cliente no lo hace, llama a tools/list nuevamente (o reinicia la sesión).

Notas sobre HTTP Streamable (`/mcp`)

--transport http expone un único endpoint MCP (por defecto http://127.0.0.1:3000/mcp) que admite GET, POST y DELETE.
Por defecto, el servidor se vincula a 127.0.0.1 por seguridad. Si te vinculas a 0.0.0.0 u otra interfaz, debes configurar --http-auth-token y considerar seriamente --http-allowed-hosts y --http-allowed-origins.
En modo HTTP, el estado de carga diferida de herramientas está aislado por sesión: cada Mcp-Session-Id obtiene su propio estado de carga de grupos de herramientas.
Protección de arranque más estricta opcional: --http-require-auth-on-public-bind true rechaza el arranque al vincularse fuera de localhost sin --http-auth-token.

supergateway + Cloudflare Baseline

Si ejecutas esto detrás de supergateway para conectores remotos de Claude.ai, fija explícitamente las banderas de transporte/sesión/protocolo del gateway:

supergateway \
  --stdio 'npx github-mcp-server-kosta -t "$GITHUB_TOKEN"' \
  --outputTransport streamableHttp \
  --streamableHttpPath /mcp \
  --protocolVersion 2025-06-18 \
  --stateful true \
  --sessionTimeout 900000 \
  --healthEndpoint /healthz \
  --healthEndpoint /readyz \
  --logLevel info

Consulta la documentación operativa:

docs/ops/baseline-connector-smoke.md
docs/ops/claude-connector-hardening.md
docs/ops/incident-playbook.md

Scripts de verificación:

scripts/smoke/remote-mcp-smoke.sh
scripts/smoke/edge-header-check.sh

Andamiaje OAuth (Preparación de Fase 2)

Este servidor ahora admite andamiaje opcional de descubrimiento/desafío OAuth para implementación gradual:

--http-oauth-resource-metadata-url: cuando las solicitudes no autenticadas son rechazadas (401), WWW-Authenticate incluye:
- Bearer resource_metadata="..."
--http-oauth-protected-resource-path: sirve un documento JSON local de Metadatos de Recursos Protegidos OAuth.
--http-oauth-authorization-server-issuer: agrega authorization_servers al JSON de metadatos.
--http-oauth-scopes: agrega scopes_supported al JSON de metadatos.
--http-oauth-cutover-path: agrega un segundo endpoint escalonado (por ejemplo, /mcp-oauth) para que puedas mantener el comportamiento de /mcp sin cambios mientras pruebas la migración de conectores que requieren autenticación.
--http-oauth-cutover-token: token requerido en el endpoint de migración; si no se configura, el servidor recurre a --http-auth-token.

Ejemplo:

npx github-mcp-server-kosta \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 3000 \
  --http-path /mcp \
  --http-auth-token "$MCP_BEARER_TOKEN" \
  --http-oauth-resource-metadata-url "https://connector.example.com/.well-known/oauth-protected-resource" \
  --http-oauth-protected-resource-path "/.well-known/oauth-protected-resource" \
  --http-oauth-authorization-server-issuer "https://auth.example.com" \
  --http-oauth-scopes "mcp.read,mcp.write"

Ejemplo de migración escalonada (/mcp abierto, /mcp-oauth protegido):

npx github-mcp-server-kosta \
  --transport http \
  --http-host 127.0.0.1 \
  --http-port 3000 \
  --http-path /mcp \
  --http-oauth-cutover-path /mcp-oauth \
  --http-oauth-cutover-token "$MCP_CUTOVER_TOKEN"

Importante:

Esto es andamiaje para implementación gradual, no una implementación completa de un servidor de autorización OAuth.
En implementaciones de conectores de Claude.ai en producción, el patrón recomendado sigue siendo OAuth propiedad de edge/gateway.

Guía de Seguridad en Lenguaje Sencillo

Si solo ejecutas esto en tu propia máquina y nada más puede acceder a él, normalmente puedes omitir la autenticación.

Si vinculas el servidor HTTP a una interfaz de red a la que otros dispositivos pueden acceder (por ejemplo, --http-host 0.0.0.0), entonces cualquier persona que pueda acceder a esa dirección podría potencialmente usar tu token de GitHub mediante estas herramientas. En ese caso, deberías:

Preferir poner la autenticación en tu gateway (supergateway / Cloudflare / tu conector) para que el servidor MCP permanezca solo en localhost.
O configurar --http-auth-token para que el endpoint de /mcp requiera un token Bearer.

Formatos de Respuesta

La mayoría de las herramientas admiten dos niveles de detalle:

summary (por defecto) — campos clave concisos, vistas previas de 5 elementos para listas
detailed — respuesta completa de la API de GitHub

Anotaciones de Herramientas

Todas las herramientas incluyen anotaciones MCP para ayudar a los clientes de IA a tomar decisiones inteligentes:

readOnlyHint — seguro de llamar sin efectos secundarios
destructiveHint — puede modificar o eliminar datos (p. ej., actualizaciones de archivos)
idempotentHint — seguro de reintentar con los mismos argumentos
openWorldHint — interactúa con la API externa de GitHub

Instrucciones del Servidor

El servidor proporciona guía de flujo de trabajo a los modelos de IA, incluyendo:

Relaciones entre herramientas (p. ej., "usa github_get_file_content para obtener el SHA antes de github_create_or_update_file")
Información sobre límites de velocidad
Requisitos de permisos del token
Recomendaciones de modo de respuesta

Licencia

Licencia MIT

Autor

Kosta Milovanovic (ildunari)

Contribuciones

Haz fork del repositorio
Crea tu rama de características
Haz commit de tus cambios
Haz push a la rama
Crea un Pull Request