Skip to main content
Glama

GitIngest MCP Server

by gooapps

GitIngest MCP Server

Un servidor MCP (Model Context Protocol) que integra GitIngest para generar archivos de contexto de repositorios de GitHub privados, diseñado para nodos de resolución de tareas LLM.

🚀 Características

  • Integración completa con GitIngest: Soporte para repositorios públicos y privados de GitHub

  • Protocolo MCP: Compatible con el estándar MCP para integración con agentes de IA

  • Dockerizado: Fácil despliegue y ejecución en contenedores

  • Configuración flexible: Patrones de inclusión/exclusión personalizables

  • Manejo robusto de errores: Fallback automático a CLI si el paquete Python no está disponible

  • Seguridad: Ejecución como usuario no-root en contenedores

📋 Requisitos

  • Python 3.11+

  • Docker (opcional, para ejecución en contenedor)

  • Token de acceso personal de GitHub (para repositorios privados)

🛠️ Instalación

Opción 1: Ejecución Directa

# Clonar o descargar el proyecto cd "Gitingest MCP" # Crear entorno virtual python -m venv venv source venv/bin/activate # En Windows: venv\Scripts\activate # Instalar dependencias pip install -r requirements.txt # Configurar variables de entorno cp env.example .env # Editar .env y agregar tu GITHUB_TOKEN

Opción 2: Docker

# Construir la imagen localmente docker build -t gitingest-mcp . # O usar docker-compose docker-compose up --build # O usar el script automatizado ./build_and_publish.sh

3. Publicación de Imagen Docker

Para publicar la imagen en GitHub Container Registry:

# Usar el script automatizado (recomendado) ./build_and_publish.sh # O manualmente docker build -t ghcr.io/gooapps/gitingest-mcp:latest . docker push ghcr.io/gooapps/gitingest-mcp:latest

⚙️ Configuración

Variables de Entorno

Crea un archivo .env basado en env.example:

# Token de GitHub (requerido para repositorios privados) GITHUB_TOKEN=ghp_your_token_here # Configuración opcional LOG_LEVEL=INFO GITINGEST_MAX_FILE_SIZE=1048576 # 1MB GITINGEST_TIMEOUT=300 # 5 minutos

Token de GitHub

Para acceder a repositorios privados, necesitas un token de acceso personal de GitHub:

  1. Ve a GitHub Settings > Personal Access Tokens

  2. Genera un nuevo token con los siguientes scopes:

    • repo (para repositorios privados)

    • public_repo (para repositorios públicos)

  3. Copia el token y configúralo en la variable GITHUB_TOKEN

🚀 Uso

Ejecución Directa

# Usar el script de inicio (recomendado) ./start.sh # O ejecutar directamente python -m gitingest_mcp.mcp_server

Docker

# Ejecutar con docker-compose docker-compose up # O ejecutar directamente docker run -e GITHUB_TOKEN=your_token_here gitingest-mcp

🔧 Herramientas MCP Disponibles

ingest_git

Descripción: Clona y analiza el repositorio indicado, generando resumen, estructura y contenido. Evita la duplicación de cabeceras Authorization en entornos Docker persistentes.

Parámetros:

  • source (requerido): URL del repositorio Git o ruta local a analizar

  • token (requerido): Access token de GitHub para autenticación

  • max_file_size (opcional): Tamaño máximo de archivo permitido para ingestión (por defecto 10 MB)

  • include_patterns (opcional): Patrones de archivos a incluir, ej. '*.py, src/'

  • exclude_patterns (opcional): Patrones de archivos a excluir, ej. 'node_modules/, *.md'

  • branch (opcional): Branch del repositorio a clonar (por defecto 'main')

Ejemplo de uso desde un cliente MCP:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/usuario/repositorio-privado", "token": "ghp_tu_token_aqui", "include_patterns": "*.py, *.js, *.md", "exclude_patterns": "node_modules/, __pycache__/, *.log", "max_file_size": 1048576, "branch": "main" } }

Casos de uso comunes:

  1. Analizar repositorio completo:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/proyecto", "token": "ghp_tu_token_aqui" } }
  1. Solo archivos de código fuente:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/proyecto", "token": "ghp_tu_token_aqui", "include_patterns": "*.py, *.js, *.ts, *.java, *.cpp, *.h", "exclude_patterns": "test/, tests/, __pycache__/, node_modules/" } }
  1. Documentación específica:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/proyecto", "token": "ghp_tu_token_aqui", "include_patterns": "*.md, *.rst, docs/, README*", "max_file_size": 524288 } }

📊 Formato de Salida

El servidor devuelve texto estructurado optimizado para consumo de LLM:

Repository: owner/repo-name Files analyzed: 42 Estimated tokens: 15.2k Directory structure: └── project-name/ ├── src/ │ ├── main.py │ └── utils.py ├── tests/ │ └── test_main.py └── README.md ================================================ FILE: src/main.py ================================================ def hello_world(): print("Hello, World!") if __name__ == "__main__": hello_world()

🔗 Integración con Nodos LLM

Configuración para GitHub Copilot (IntelliJ/VSCode)

Para integrar con GitHub Copilot, crea o actualiza el archivo de configuración MCP:

Archivo: ~/.config/github-copilot/intellij/mcp.json (IntelliJ) o ~/.config/github-copilot/vscode/mcp.json (VSCode)

{ "servers": { "gitingest": { "command": "docker", "args": [ "run", "-i", "--rm", "docker.io/develgooapps/gitingest-mcp:main-26b875d" ] } } }

Configuración usando Imagen Docker Local

Si prefieres construir la imagen localmente:

{ "servers": { "gitingest": { "command": "docker", "args": [ "run", "-i", "--rm", "gitingest-mcp:latest" ] } } }

Configuración para Claude Desktop

Para usar con Claude Desktop, agrega al archivo de configuración:

Archivo: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{ "mcpServers": { "gitingest": { "command": "docker", "args": [ "run", "-i", "--rm", "docker.io/develgooapps/gitingest-mcp:main-26b875d" ] } } }

Configuración para Cline (VSCode Extension)

Para usar con la extensión Cline en VSCode:

{ "mcpServers": { "gitingest": { "command": "docker", "args": [ "run", "-i", "--rm", "docker.io/develgooapps/gitingest-mcp:main-26b875d" ] } } }

🎯 Guía de Uso Práctica

Configuración Inicial Rápida

  1. Obtener un Token de GitHub:

    # Ve a: https://github.com/settings/tokens # Genera un nuevo token con permisos: # - repo (para repositorios privados) # - public_repo (para repositorios públicos) # Nota: Este token se usará directamente en las llamadas al MCP
  2. Configurar en GitHub Copilot (IntelliJ/VSCode):

    # Crear directorio de configuración si no existe mkdir -p ~/.config/github-copilot/intellij # Crear archivo mcp.json cat > ~/.config/github-copilot/intellij/mcp.json << 'EOF' { "servers": { "gitingest": { "command": "docker", "args": [ "run", "-i", "--rm", "docker.io/develgooapps/gitingest-mcp:main-26b875d" ] } } } EOF
  3. Reiniciar GitHub Copilot para que cargue la nueva configuración.

Casos de Uso Comunes

1. Análisis Completo de Repositorio

Escenario: Necesitas entender un repositorio completo para hacer contribuciones o debugging.

Comando en el chat de Copilot:

@gitingest analiza el repositorio https://github.com/empresa/proyecto-backend Token: ghp_tu_token_aqui

Llamada MCP interna:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/proyecto-backend", "token": "ghp_tu_token_aqui" } }

2. Análisis de Solo Código Fuente

Escenario: Solo quieres ver el código, sin documentación ni archivos de configuración.

Comando en el chat:

@gitingest analiza solo el código fuente de https://github.com/empresa/api-service Incluye: *.py, *.js, *.ts, *.java Excluye: tests/, docs/, *.md, node_modules/ Token: ghp_tu_token_aqui

Llamada MCP interna:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/api-service", "token": "ghp_tu_token_aqui", "include_patterns": "*.py, *.js, *.ts, *.java", "exclude_patterns": "tests/, docs/, *.md, node_modules/" } }

3. Análisis de Documentación

Escenario: Solo necesitas la documentación del proyecto.

Comando en el chat:

@gitingest extrae solo la documentación de https://github.com/empresa/frontend-app Incluye: *.md, *.rst, docs/, README*, CHANGELOG* Token: ghp_tu_token_aqui

Llamada MCP interna:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/frontend-app", "token": "ghp_tu_token_aqui", "include_patterns": "*.md, *.rst, docs/, README*, CHANGELOG*" } }

4. Análisis de Branch Específico

Escenario: Quieres analizar una feature branch específica.

Comando en el chat:

@gitingest analiza la rama feature/nueva-funcionalidad del repo https://github.com/empresa/proyecto Token: ghp_tu_token_aqui

Llamada MCP interna:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/proyecto", "token": "ghp_tu_token_aqui", "branch": "feature/nueva-funcionalidad" } }

5. Análisis con Límite de Tamaño

Escenario: El repo es muy grande y solo quieres archivos pequeños.

Comando en el chat:

@gitingest analiza https://github.com/empresa/proyecto-grande pero solo archivos menores a 500KB Token: ghp_tu_token_aqui

Llamada MCP interna:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/empresa/proyecto-grande", "token": "ghp_tu_token_aqui", "max_file_size": 512000 } }

Flujo de Trabajo Típico

  1. Identificar Repositorio: Obtén la URL del repositorio que necesitas analizar

  2. Determinar Scope: Decide qué archivos necesitas (código, docs, config, etc.)

  3. Usar Filtros: Aplica patrones de inclusión/exclusión según tu necesidad

  4. Ejecutar Análisis: Usa el comando con @gitingest en tu cliente MCP

  5. Revisar Resultados: El MCP retornará el contenido estructurado del repositorio

Consejos de Uso

  • Repositorios Grandes: Usa exclude_patterns para evitar node_modules/, __pycache__/, .git/

  • Análisis Específico: Usa include_patterns para enfocarte en tipos de archivo específicos

  • Branches: Especifica el branch si no quieres analizar main/master

  • Tamaño de Archivos: Limita max_file_size para evitar archivos binarios grandes

  • Tokens: Usa tokens con permisos mínimos necesarios para el repositorio

🐳 Docker Compose

El archivo docker-compose.yml incluye:

  • Configuración de salud del contenedor

  • Límites de recursos

  • Política de reinicio

  • Configuración de seguridad

  • Sistema de archivos de solo lectura

🔒 Seguridad

  • Ejecución como usuario no-root en contenedores

  • Sistema de archivos de solo lectura

  • Límites de recursos configurados

  • Validación de URLs de GitHub

  • Manejo seguro de tokens

🐛 Solución de Problemas

Problemas Comunes y Soluciones

1. Error: "Authentication failed" o "Repository not found"

Síntomas:

Error: Repository not found or access denied HTTP 404: Not Found

Soluciones:

  • Verifica que la URL del repositorio sea correcta

  • Asegúrate de que el token de GitHub tenga los permisos necesarios:

    • repo para repositorios privados

    • public_repo para repositorios públicos

  • Para repositorios de organizaciones, el token debe tener acceso a la organización

# Verificar permisos del token curl -H "Authorization: token TU_TOKEN" https://api.github.com/user

2. Error: "Docker image not found"

Síntomas:

Unable to find image 'docker.io/develgooapps/gitingest-mcp:main-26b875d'

Soluciones:

# Descargar la imagen manualmente docker pull docker.io/develgooapps/gitingest-mcp:main-26b875d # O construir localmente cd "Gitingest MCP" docker build -t gitingest-mcp:latest . # Actualizar mcp.json para usar imagen local # Cambiar "docker.io/develgooapps/gitingest-mcp:main-26b875d" por "gitingest-mcp:latest"

3. Error: "GITHUB_TOKEN not set"

Síntomas:

Error: GitHub token is required but not provided

Soluciones:

  • Verificar que estés pasando el token correctamente en la llamada al MCP

  • Asegurar que el token no tenga espacios ni caracteres especiales

  • El token debe incluirse en cada llamada individual al MCP, no en la configuración

Ejemplo correcto de uso:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/usuario/repo", "token": "ghp_tu_token_sin_espacios" } }

4. Error: "Rate limit exceeded"

Síntomas:

API rate limit exceeded for user

Soluciones:

  • Esperar una hora antes de hacer más requests

  • Usar un token de GitHub autenticado (aumenta el límite de 60 a 5000 requests/hora)

  • Para uso intensivo, considera usar GitHub Apps

5. Error: "File too large" o "Repository too large"

Síntomas:

Error: File exceeds maximum size limit Warning: Repository is very large

Soluciones:

{ "name": "ingest_git", "arguments": { "source": "https://github.com/user/large-repo", "token": "ghp_tu_token", "max_file_size": 1048576, "exclude_patterns": "*.zip, *.tar.gz, *.pdf, *.png, *.jpg, node_modules/, .git/" } }

6. Error: "MCP server not responding"

Síntomas:

  • El chat no reconoce @gitingest

  • No aparecen las herramientas del MCP

Soluciones:

  1. Verificar que Docker esté ejecutándose:

docker ps
  1. Probar la imagen manualmente:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \ docker run -i --rm \ docker.io/develgooapps/gitingest-mcp:main-26b875d
  1. Reiniciar GitHub Copilot/IDE después de cambios en mcp.json

  2. Verificar logs de Docker:

docker logs $(docker ps -q --filter ancestor=docker.io/develgooapps/gitingest-mcp:main-26b875d)

Mejores Prácticas

Gestión de Tokens

  • Rotación: Rota los tokens de GitHub regularmente

  • Scope Mínimo: Usa tokens con el mínimo scope necesario

  • Seguridad: Nunca compartas tokens en código o logs

  • Uso Dinámico: El token se pasa directamente en cada llamada al MCP, no se almacena en configuración

Optimización de Rendimiento

  • Filtros Inteligentes: Usa patrones de exclusión para evitar archivos innecesarios

{ "exclude_patterns": "node_modules/, __pycache__/, .git/, *.log, *.tmp, dist/, build/" }
  • Límites de Tamaño: Establece límites apropiados para tu caso de uso

{ "max_file_size": 524288 // 512KB para análisis de código }

Uso Eficiente

  • Branches Específicos: Analiza branches específicos en lugar de todo el repositorio

  • Análisis Incremental: Para repos grandes, analiza directorios específicos

  • Cache Local: Docker cachea las imágenes, aprovecha esto para múltiples usos

Verificación de Configuración

Usa este script para verificar que todo esté configurado correctamente:

#!/bin/bash echo "🔍 Verificando configuración GitIngest MCP..." # Verificar Docker if ! command -v docker &> /dev/null; then echo "❌ Docker no está instalado" exit 1 fi echo "✅ Docker está disponible" # Verificar imagen if docker image inspect docker.io/develgooapps/gitingest-mcp:main-26b875d &> /dev/null; then echo "✅ Imagen Docker encontrada" else echo "⚠️ Descargando imagen Docker..." docker pull docker.io/develgooapps/gitingest-mcp:main-26b875d fi # Verificar archivo de configuración MCP_CONFIG="$HOME/.config/github-copilot/intellij/mcp.json" if [ -f "$MCP_CONFIG" ]; then echo "✅ Archivo mcp.json encontrado" if grep -q "gitingest" "$MCP_CONFIG"; then echo "✅ Configuración gitingest encontrada" else echo "❌ Configuración gitingest no encontrada en mcp.json" fi else echo "❌ Archivo mcp.json no encontrado en $MCP_CONFIG" fi # Verificar que el MCP responda echo "🧪 Probando conexión con el MCP..." if echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | \ docker run -i --rm docker.io/develgooapps/gitingest-mcp:main-26b875d > /dev/null 2>&1; then echo "✅ MCP responde correctamente" else echo "❌ MCP no responde - verificar imagen Docker" fi echo "🎉 Verificación completada" echo "💡 Recuerda: El token de GitHub se pasa dinámicamente en cada llamada al MCP"

📝 Logs

Los logs se pueden configurar con la variable LOG_LEVEL:

  • DEBUG: Información detallada

  • INFO: Información general (por defecto)

  • WARNING: Solo advertencias y errores

  • ERROR: Solo errores

🤝 Contribución

  1. Fork el proyecto

  2. Crea una rama para tu feature (git checkout -b feature/AmazingFeature)

  3. Commit tus cambios (git commit -m 'Add some AmazingFeature')

  4. Push a la rama (git push origin feature/AmazingFeature)

  5. Abre un Pull Request

📄 Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

🆘 Soporte

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gooapps/gitingest-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server