Git MCP Server

---

Herramientas

28 operaciones de git organizadas en siete categorías:

Categoría	Herramientas	Descripción
Gestión de repositorios	git_init, git_clone, git_status, git_clean	Inicializar repos, clonar desde remotos, ver estado, limpiar archivos no rastreados
Staging y commits	git_add, git_commit, git_diff	Preparar cambios, crear commits, comparar cambios
Historial e inspección	git_log, git_show, git_blame, git_reflog	Ver historial de commits, inspeccionar objetos, rastrear autoría, ver registros de referencias
Análisis	git_changelog_analyze	Recopilar contexto de git e instrucciones para análisis de changelog impulsado por LLM
Ramas y fusiones	git_branch, git_checkout, git_merge, git_rebase, git_cherry_pick	Gestionar ramas, cambiar de contexto, integrar cambios, aplicar commits específicos
Operaciones remotas	git_remote, git_fetch, git_pull, git_push	Configurar remotos, obtener actualizaciones, sincronizar repositorios, publicar cambios
Flujos de trabajo avanzados	git_tag, git_stash, git_reset, git_worktree, git_set_working_dir, git_clear_working_dir, git_wrapup_instructions	Etiquetar versiones (listar/crear/eliminar/verificar), guardar cambios, restablecer estado, gestionar árboles de trabajo, establecer/limpiar directorio de sesión

Recursos

Recurso	URI	Descripción
Directorio de trabajo de Git	git://working-directory	El directorio de trabajo de la sesión actual, establecido mediante git_set_working_dir.

Prompts

Prompt	Descripción	Parámetros
Resumen de Git	Protocolo de flujo de trabajo para completar sesiones de git: revisar, documentar, confirmar y etiquetar cambios.	changelogPath, createTag.

Primeros pasos

Entorno de ejecución

Funciona con Bun y Node.js. El entorno de ejecución se detecta automáticamente.

Entorno de ejecución	Comando	Versión mínima
Node.js	npx @cyanheads/git-mcp-server@latest	>= 20.0.0
Bun	bunx @cyanheads/git-mcp-server@latest	>= 1.2.0

Configuración del cliente MCP

Agrega lo siguiente a la configuración de tu cliente MCP (por ejemplo, cline_mcp_settings.json). Actualiza las variables de entorno para que coincidan con tu configuración, especialmente los campos de identidad de git.

{
  "mcpServers": {
    "git-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["@cyanheads/git-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "GIT_BASE_DIR": "~/Developer/",
        "LOGS_DIR": "~/Developer/logs/git-mcp-server/",
        "GIT_USERNAME": "cyanheads",
        "GIT_EMAIL": "casey@caseyjhand.com",
        "GIT_SIGN_COMMITS": "true"
      }
    }
  }
}

Usuarios de Bun: reemplaza "command": "npx" con "command": "bunx".

Para HTTP Streamable, establece MCP_TRANSPORT_TYPE=http y MCP_HTTP_PORT=3015.

Características

Construido sobre mcp-ts-template.

Característica	Detalles
Herramientas declarativas	Define capacidades en archivos únicos y autocontenidos. El framework gestiona el registro, la validación y la ejecución.
Manejo de errores	Sistema unificado McpError para respuestas de error consistentes y estructuradas.
Autenticación	Admite modos none, jwt y oauth.
Almacenamiento conectable	Intercambia backends (in-memory, filesystem, Supabase, Cloudflare KV/R2) sin cambiar la lógica de negocio.
Observabilidad	Registro estructurado (Pino) y OpenTelemetry opcional con instrumentación automática para trazas y métricas.
Inyección de dependencias	Construido con tsyringe para una arquitectura desacoplada y comprobable.
Multi-entorno	Detecta automáticamente Bun o Node.js y utiliza el método de creación de procesos adecuado.
Arquitectura de proveedores	Sistema de proveedores de git conectable. Actual: CLI. Planificado: isomorphic-git para implementación en el borde.
Gestión del directorio de trabajo	Contexto de directorio específico de la sesión para flujos de trabajo con múltiples repositorios.
Identidad de git configurable	Sobrescribe la información de autor/committer mediante variables de entorno, con respaldo a la configuración global de git.
Firma de commits	Firma GPG/SSH (habilitada por defecto) para commits, fusiones, rebases, cherry-picks y etiquetas. Respaldo silencioso a sin firma en caso de fallo con campos signed/signingWarning en las respuestas.
Seguridad	Las operaciones destructivas (git clean, git reset --hard) requieren banderas de confirmación explícitas.

Seguridad

• Todas las rutas de archivo se validan y sanean para prevenir el recorrido de directorios.
• GIT_BASE_DIR opcional restringe las operaciones a un árbol de directorios específico para el sandboxing multiinquilino.
• Los comandos de git utilizan argumentos validados mediante la creación de procesos, sin interpolación de shell.
• Soporte de JWT y OAuth para implementaciones autenticadas.
• Limitación de velocidad opcional mediante el servicio RateLimiter gestionado por DI.
• Todas las operaciones se registran con contexto de solicitud para auditoría.

Configuración

Toda la configuración se valida al inicio en src/config/index.ts. Variables de entorno clave:

Variable	Descripción	Predeterminado
MCP_TRANSPORT_TYPE	Transporte: stdio o http.	stdio
MCP_SESSION_MODE	Modo de sesión HTTP: stateless, stateful o auto.	auto
MCP_RESPONSE_FORMAT	Formato de respuesta: json (optimizado para LLM), markdown (legible para humanos) o auto.	json
MCP_RESPONSE_VERBOSITY	Nivel de detalle: minimal, standard o full.	standard
MCP_HTTP_PORT	Puerto del servidor HTTP.	3015
MCP_HTTP_HOST	Nombre de host del servidor HTTP.	127.0.0.1
MCP_HTTP_ENDPOINT_PATH	Ruta del endpoint de solicitudes MCP.	/mcp
MCP_AUTH_MODE	Modo de autenticación: none, jwt o oauth.	none
STORAGE_PROVIDER_TYPE	Backend de almacenamiento: in-memory, filesystem, supabase, cloudflare-kv, r2.	in-memory
OTEL_ENABLED	Habilitar OpenTelemetry.	false
MCP_LOG_LEVEL	Nivel mínimo de registro: debug, info, warn, error.	info
GIT_SIGN_COMMITS	Firma GPG/SSH para commits, merges, rebases, cherry-picks y tags. Vuelve a sin firma en caso de error (ver respuesta signed/signingWarning).	true
GIT_AUTHOR_NAME	Nombre del autor de Git. Aliases: GIT_USERNAME, GIT_USER. Vuelve a la configuración global de git.	(none)
GIT_AUTHOR_EMAIL	Correo electrónico del autor de Git. Aliases: GIT_EMAIL, GIT_USER_EMAIL. Vuelve a la configuración global de git.	(none)
GIT_BASE_DIR	Ruta absoluta para restringir todas las operaciones de git a un árbol de directorios específico.	(none)
GIT_WRAPUP_INSTRUCTIONS_PATH	Ruta a un archivo markdown personalizado con instrucciones de flujo de trabajo.	(none)
MCP_AUTH_SECRET_KEY	Requerido para autenticación jwt. Clave secreta de 32+ caracteres.	(none)
OAUTH_ISSUER_URL	Requerido para autenticación oauth. URL del proveedor OIDC.	(none)

Ejecutar el servidor

Mediante gestor de paquetes (sin instalación)

npx @cyanheads/git-mcp-server@latest

Configura mediante variables de entorno o la configuración de tu cliente MCP.

Desarrollo local

# Build and run
npm run rebuild
npm run start:stdio   # or start:http

# Dev mode with hot reload
npm run dev:stdio     # or dev:http

# Checks and tests
npm run devcheck      # lint, format, typecheck
npm test

Cloudflare Workers

npm run build:worker   # Build the worker bundle
npm run deploy:dev     # Run locally with Wrangler
npm run deploy:prod    # Deploy to Cloudflare

Estructura del proyecto

Directorio	Propósito
src/mcp-server/tools	Definiciones de herramientas (*.tool.ts). Las capacidades de Git residen aquí.
src/mcp-server/resources	Definiciones de recursos (*.resource.ts). Fuentes de datos de contexto de Git.
src/mcp-server/transports	Implementaciones de transporte HTTP y STDIO, incluida la autenticación.
src/storage	Abstracción de StorageService e implementaciones de proveedores.
src/services	Proveedor de servicios Git (operaciones git basadas en CLI).
src/container	Registros y tokens del contenedor de DI.
src/utils	Utilidades de registro, manejo de errores, rendimiento y seguridad.
src/config	Análisis y validación de variables de entorno (Zod).
tests/	Pruebas unitarias y de integración, que reflejan la estructura de src/.

Formato de respuesta

Configura el formato de salida y la verbosidad mediante MCP_RESPONSE_FORMAT y MCP_RESPONSE_VERBOSITY.

Formato JSON (predeterminado, optimizado para consumo por LLM):

{
  "success": true,
  "branch": "main",
  "staged": ["src/index.ts", "README.md"],
  "unstaged": ["package.json"],
  "untracked": []
}

Formato Markdown (legible para humanos):

# Git Status: main

## Staged (2)
- src/index.ts
- README.md

## Unstaged (1)
- package.json

El LLM siempre recibe los datos estructurados completos mediante responseFormatter — listas de archivos completas, metadatos, marcas de tiempo — independientemente de lo que muestre el cliente. La verbosidad controla cuánto detalle se incluye: minimal (solo campos principales), standard (equilibrado) o full (todo).

Guía de desarrollo

Consulta AGENTS.md para arquitectura, patrones de desarrollo de herramientas y reglas de contribución.

Pruebas

Las pruebas utilizan el ejecutor de pruebas de Bun con compatibilidad con Vitest.

bun test              # Run all tests
bun test --coverage   # With coverage
bun run devcheck      # Lint, format, typecheck, audit

Hoja de ruta

El servidor utiliza una arquitectura basada en proveedores para operaciones de git:

• Proveedor CLI (actual) — Cobertura completa de 28 herramientas mediante la CLI nativa de git. Requiere instalación local de git.
• Proveedor git isomórfico (planificado) — Implementación pura en JS para despliegue en el edge (Cloudflare Workers, Vercel Edge, Deno Deploy). Utiliza isomorphic-git.
• Proveedor de API de GitHub (quizás) — Operaciones nativas en la nube mediante las API REST/GraphQL de GitHub, sin necesidad de repositorio local.

Contribuciones

Las incidencias y solicitudes de extracción son bienvenidas. Ejecuta las verificaciones antes de enviar:

npm run devcheck
npm test

Licencia

Apache 2.0. Consulta LICENSE.

---