GitHub MCP Server

Integra funcionalidades de GitHub en asistentes de IA usando la CLI de GitHub.

GitHub
8
Prueba este MCPPatrocinado

Documentación

GitHub MCP Server

Un servidor Model Context Protocol (MCP) basado en Spring Boot que proporciona herramientas de integración con GitHub para asistentes de IA como Claude Desktop.

Resumen

Este servidor implementa el Model Context Protocol para exponer operaciones de GitHub como herramientas que pueden ser utilizadas por clientes MCP. Aprovecha la GitHub CLI (gh) para realizar diversas operaciones de GitHub, incluyendo gestión de repositorios, seguimiento de incidencias, gestión de pull requests y más. Esto proporciona una alternativa ligera al servidor MCP oficial de GitHub que no requiere Docker.

Inicio rápido para Claude Desktop

Para usar este servidor con Claude Desktop, añade lo siguiente a tu archivo de configuración de Claude:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
      "env": {}
    }
  }
}

Reemplaza /path/to/gh_mcp_server con la ruta real a tu directorio del proyecto.

Características

Operaciones de repositorio

  • Listar repositorios del usuario autenticado
  • Buscar repositorios en GitHub
  • Obtener información detallada de repositorios
  • Listar ramas en un repositorio
  • Crear nuevas ramas
  • Obtener contenido de archivos de repositorios
  • Obtener historial de commits

Gestión de incidencias

  • Listar incidencias (abiertas, cerradas o todas)
  • Obtener información detallada de incidencias
  • Crear nuevas incidencias
  • Cerrar incidencias
  • Añadir comentarios a incidencias
  • Editar título y cuerpo de incidencias

Gestión de pull requests

  • Listar pull requests
  • Obtener información detallada de pull requests
  • Crear nuevas pull requests
  • Fusionar pull requests (merge, squash o rebase)
  • Cerrar pull requests
  • Añadir comentarios a pull requests

Workflows y acciones

  • Listar workflows en un repositorio
  • Listar ejecuciones de workflows con filtrado opcional
  • Ver información detallada de ejecuciones de workflows

Gestión de releases

  • Listar releases
  • Ver detalles de releases
  • Crear nuevos releases (con opciones de borrador/pre-lanzamiento)

Operaciones de usuario

  • Obtener detalles del usuario autenticado

Requisitos previos

  • Java 21 o superior - Utiliza características modernas de Java (virtual threads, records, pattern matching)
  • GitHub CLI (gh) - Debe estar instalada y autenticada
  • Gradle - Wrapper incluido en el proyecto

¿Por qué usar este servidor MCP?

  • 🚀 Ligero: No requiere Docker, implementación pura en Java
  • 🔧 Integral: 26 operaciones de GitHub que cubren flujos de trabajo completos
  • ⚡ Rápido: Integración directa con GitHub CLI con respuestas JSON optimizadas
  • 🧪 Bien probado: Más de 75 casos de prueba que garantizan la fiabilidad
  • 🛡️ Seguro: Aprovecha la autenticación existente de GitHub CLI

Configuración

  1. Instalar GitHub CLI

    # macOS
brew install gh

# or download from https://cli.github.com/

  2. Autenticarse con GitHub

    gh auth login

  3. Clonar y compilar el proyecto

    git clone <repository-url>
cd gh_mcp_server
./gradlew build

    Nota: La compilación crea automáticamente un enlace simbólico independiente de versión gh_mcp_server.jar → gh_mcp_server-1.0.0.jar

  4. Configurar Claude Desktop

    Después de compilar, configura Claude para usar este servidor MCP. Tienes dos opciones:

    Opción A: Usando el archivo JAR (Recomendado)

    {
  "mcpServers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server.jar"],
      "env": {}
    }
  }
}

    Nota: Un enlace simbólico gh_mcp_server.jar apunta a la versión actual (gh_mcp_server-1.0.0.jar). Esto proporciona una implementación independiente de la versión. Para una implementación específica de versión, usa el nombre de archivo completo con versión.

    Opción B: Usando Gradle

    {
  "mcpServers": {
    "github": {
      "command": "./gradlew",
      "args": ["bootRun"],
      "cwd": "/path/to/gh_mcp_server",
      "env": {}
    }
  }
}

  5. Reinicia Claude Desktop para cargar la nueva configuración del servidor

Ejemplos de uso

Después de configurar Claude Desktop, puedes usar lenguaje natural para interactuar con GitHub:

Gestión de repositorios

  • "Lista mis repositorios" → Muestra tus repositorios con detalles
  • "Lista mis repositorios privados" → Filtra por visibilidad (público/privado/interno)
  • "Busca repositorios de Spring Boot con más de 1000 estrellas"
  • "Muéstrame detalles del repositorio microsoft/vscode"
  • "Obtén los últimos 5 commits de mi repositorio de proyecto"
  • "¿Qué ramas existen en mi repositorio de proyecto?"

Seguimiento de incidencias

  • "Lista las incidencias abiertas en mi proyecto" → Lista las incidencias abiertas actuales
  • "Muéstrame los detalles de la incidencia #123" → Obtiene información específica de la incidencia
  • "Crea una nueva incidencia titulada 'Error: el inicio de sesión falla' con descripción..."
  • "Cierra la incidencia #123 y añade un comentario 'Corregido en la última versión'"

Gestión de pull requests

  • "Lista todas las pull requests en el repositorio kubernetes/kubernetes"
  • "Muéstrame los detalles del PR #456"
  • "Crea una pull request desde mi feature-branch a main"
  • "Fusiona el PR #789 usando estrategia squash"

CI/CD y releases

  • "Muéstrame todos los workflows en este repositorio" → Lista GitHub Actions
  • "¿Cuál es el estado de las ejecuciones recientes de workflows?"
  • "Lista los releases del repositorio golang/go"
  • "Crea un nuevo release v2.1.0 como borrador"

Operaciones de archivos

  • "Obtén el contenido de package.json de mi proyecto"
  • "Muéstrame el archivo README de la rama main"

Verificación

Si el servidor no se inicia, comprueba que:

  • Java 21+ está instalado y en tu PATH
  • GitHub CLI está instalada y autenticada (gh auth status)
  • La ruta del archivo JAR en la configuración es correcta
  • Claude Desktop ha sido reiniciado

Pruebas del servidor

Para probar el servidor de forma independiente (sin Claude):

./gradlew bootRun

El servidor se iniciará en modo STDIO y esperará mensajes del protocolo MCP. Sin embargo, para uso normal, el servidor debe configurarse para que Claude Desktop lo ejecute automáticamente como se muestra arriba.

Comandos de desarrollo

# Build the project and run all tests
./gradlew build

# Run tests (command syntax validation only)
./gradlew test

# Run tests including GitHub CLI integration tests
./gradlew test -Dtest.gh.integration=true

# Format code with Spotless (Google Java Format)
./gradlew spotlessApply

# Check code formatting without applying changes
./gradlew spotlessCheck

# Clean build artifacts
./gradlew clean

# Run the server locally for testing
./gradlew bootRun

Cobertura de pruebas

El proyecto incluye una cobertura de pruebas integral:

  • Más de 75 casos de prueba que validan las 26 operaciones de GitHub
  • Pruebas de sintaxis de comandos - Verifican la construcción exacta de comandos gh
  • Pruebas de casos límite - Manejan caracteres especiales, Unicode, valores nulos
  • Pruebas de integración - Ejecución opcional de GitHub CLI real
  • Pruebas de manejo de errores - Validan modos de fallo elegantes

Consulta src/test/java/com/kousenit/gh_mcp_server/TEST_README.md para la documentación detallada de pruebas.

Configuración

El servidor usa la configuración predeterminada de Spring Boot. Puedes personalizar los ajustes en src/main/resources/application.properties.

Opciones de configuración clave

  • github.defaultBranch - Nombre de rama predeterminado para operaciones (predeterminado: main)
  • spring.threads.virtual.enabled - Habilita virtual threads para mejor rendimiento (predeterminado: true)
  • El servidor MCP se ejecuta en modo STDIO para integración CLI

Operaciones disponibles (26 en total)

Operaciones de repositorio

  • listRepositories - Lista los repositorios del usuario con filtro de visibilidad opcional (público/privado/interno)
  • searchRepositories - Busca repositorios en GitHub
  • getRepository - Obtiene información detallada del repositorio
  • getCommitHistory - Obtiene el historial de commits del repositorio con límite configurable
  • listBranches - Lista las ramas del repositorio
  • createBranch - Crea una nueva rama

Gestión de incidencias

  • listIssues - Lista incidencias en el repositorio
  • getIssue - Obtiene detalles de una incidencia específica
  • createIssue - Crea una nueva incidencia
  • closeIssue - Cierra una incidencia
  • commentOnIssue - Añade comentario a una incidencia
  • editIssue - Edita título/cuerpo de una incidencia

Gestión de pull requests

  • listPullRequests - Lista pull requests
  • getPullRequest - Obtiene detalles del PR
  • createPullRequest - Crea una nueva pull request
  • mergePullRequest - Fusiona PR (merge/squash/rebase)
  • closePullRequest - Cierra pull request
  • commentOnPullRequest - Añade comentario al PR

Workflows y CI/CD

  • listWorkflows - Lista workflows del repositorio
  • listWorkflowRuns - Lista ejecuciones de workflows con filtrado
  • getWorkflowRun - Obtiene detalles de ejecución de workflow

Gestión de releases

  • listReleases - Lista releases del repositorio
  • getRelease - Obtiene detalles de release
  • createRelease - Crea nuevo release (opciones de borrador/pre-lanzamiento)

Operaciones de archivos y usuario

  • getFileContents - Obtiene contenido de archivos del repositorio
  • getMe - Obtiene detalles del usuario autenticado

Todas las operaciones devuelven respuestas JSON optimizadas y soportan un manejo integral de errores.

Solución de problemas

Problemas comunes

"gh: command not found"

  • Instala GitHub CLI desde https://cli.github.com/
  • Asegúrate de que gh esté en tu PATH del sistema
  • Prueba con gh --version

Errores de autenticación

  • Ejecuta gh auth login para autenticarte
  • Comprueba el estado con gh auth status
  • Asegúrate de tener acceso a los repositorios a los que intentas acceder

Fallos al iniciar el servidor

  • Verifica que Java 21+ esté instalado: java --version
  • Comprueba la ruta del archivo JAR en la configuración de Claude
  • Busca mensajes de error en los registros de Claude Desktop
  • Asegúrate de que el servidor no esté ya ejecutándose en otra instancia

Tiempos de espera agotados en comandos

  • Los repositorios grandes o las redes lentas pueden causar tiempos de espera
  • El tiempo de espera predeterminado es de 30 segundos por operación
  • Comprueba tu conexión a internet y el estado de la API de GitHub

Errores de permisos denegados

  • Asegúrate de que GitHub CLI tenga los permisos adecuados para el repositorio
  • Para repositorios de organizaciones, comprueba si tienes el acceso adecuado
  • Algunas operaciones requieren permisos de escritura (crear, editar, fusionar, cerrar)

Consejos de rendimiento

  • Usa nombres específicos de repositorio y propietario para respuestas más rápidas
  • Limita los resultados de búsqueda con parámetros de límite apropiados
  • El servidor usa virtual threads para un rendimiento concurrente óptimo
  • GitHub CLI maneja la limitación de tasa automáticamente

Obtener ayuda

  • Consulta la documentación de GitHub CLI: gh help
  • Revisa el protocolo MCP: https://modelcontextprotocol.io/
  • Para problemas del servidor, habilita el registro de depuración en application.properties

Consideraciones de implementación

Versionado de JAR

El proceso de compilación genera archivos JAR con números de versión en el nombre de archivo (p. ej., gh_mcp_server-1.0.0.jar). Al implementar o actualizar:

  1. Implementación inicial: Usa la versión actual en tu configuración de Claude Desktop:

    "args": ["-jar", "/path/to/gh_mcp_server/build/libs/gh_mcp_server-1.0.0.jar"]

  2. Actualizaciones de versión: Al actualizar a una nueva versión, debes:

    • Compilar la nueva versión: ./gradlew build
    • Actualizar tu configuración de Claude Desktop con el nuevo nombre de archivo JAR
    • Reiniciar Claude Desktop para cargar la nueva versión

  3. Implementación independiente de versión: Para una implementación más fácil, puedes:

    • Usar el enlace simbólico generado automáticamente gh_mcp_server.jar (creado automáticamente durante la compilación)
    • Usar la opción de Gradle (usa automáticamente la última compilación)
    • Usar un script de implementación que maneje las actualizaciones de versión

    Gestión automática de enlaces simbólicos: El proceso de compilación crea y mantiene automáticamente el enlace simbólico:

    • ./gradlew build crea gh_mcp_server.jar → gh_mcp_server-X.Y.Z.jar
    • ./gradlew clean build recrea el enlace simbólico con la versión correcta
    • No se requiere gestión manual de enlaces simbólicos

Gestión de configuración

  • Mantén tu configuración de Claude Desktop en control de versiones
  • Documenta la versión específica del JAR que se usa en producción
  • Considera usar variables de entorno para rutas en scripts de implementación

Stack tecnológico

  • Spring Boot 3.5.0 - Marco de aplicación
  • Spring AI 1.0.0 - Integración de IA y capacidades de servidor MCP
  • Java 21 - Lenguaje de programación con soporte de virtual threads
  • GitHub CLI - Integración con la API de GitHub
  • Gradle - Herramienta de compilación
  • Spotless - Formato de código con Google Java Format

Características clave de implementación

  • Virtual Threads (Java 21) - Operaciones de E/S concurrentes eficientes
  • ProcessBuilder - Ejecución segura de comandos con soporte de tiempo de espera
  • Records (Java 17) - Estructuras de datos inmutables para resultados de comandos
  • Pattern Matching - Sintaxis moderna de Java para comprobación de tipos
  • String Templates - Usando String.formatted() para una construcción de cadenas más limpia

Licencia

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