Github MCP Server Java

GitHub MCP Server — Java / Spring AI

Un servidor MCP listo para producción que conecta cualquier agente de IA compatible con MCP a la API de GitHub. Gestiona repositorios, issues, pull requests y búsquedas, todo mediante lenguaje natural.

Transporte: HTTP/SSE en el puerto 8080, compatible con Cursor y Claude Desktop de forma inmediata.

---

¿Por qué este servidor?

Capacidad	Este servidor	API REST de GitHub
Gestión de repositorios	✅	✅
Operaciones de issues y PRs	✅	✅
Control de ramas y commits	✅	✅
Búsqueda de código y usuarios	✅	✅
Interfaz de lenguaje natural	✅	❌
Protocolo MCP (SSE)	✅	❌
Java / Spring AI	✅	❌
Soporte para GitHub Enterprise	✅	✅

---

Herramientas (38 en total)

Categoría	Cantidad	Herramientas
Repositorio	11	create_repository, fork_repository, get_repository, list_commits, get_commit, get_file_contents, create_or_update_file, delete_file, create_branch, list_branches, merge_branch
Issues	11	create_issue, update_issue, add_issue_comment, list_issues, get_issue, close_issue, reopen_issue, assign_issue, unassign_issue, add_issue_labels, remove_issue_label
Pull Requests	10	create_pull_request, update_pull_request, list_pull_requests, get_pull_request, merge_pull_request, close_pull_request, reopen_pull_request, add_pull_request_comment, create_pull_request_review, submit_pull_request_review
Búsqueda	4	search_code, search_issues, search_repositories, search_users
Usuarios	3	get_authenticated_user, get_user, list_user_repositories

---

Inicio rápido

# 1. Build
mvn clean package

# 2. Set credentials
export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_...

# 3. Run (SSE transport — port 8080)
java -jar target/github-mcp-server-1.0.0.jar

# 4. Verify
curl http://localhost:8080/health

# 5. Inspect all tools
npx @modelcontextprotocol/inspector http://localhost:8080/sse

Obtén tu token desde Configuración de GitHub → Configuración de desarrollador → Tokens de acceso personal. Para GitHub Enterprise, establece GITHUB_HOST a la URL de tu instancia.

---

Arquitectura

MCP Client (Cursor / Claude Desktop / other)
    │   HTTP/SSE transport (/sse + /mcp/message)
    ▼
Tool class  (@McpTool — thin delegation layer, validates required params)
    ▼
Service interface + impl  (business logic, error mapping, pagination)
    ▼
GitHubRestClient  (typed HTTP gateway, PAT auth, exception handling)
    ▼
GitHub REST API

La arquitectura está estrictamente en capas:

• client/ — límite de integración con GitHub (HTTP, autenticación Bearer, manejo de errores)
• service/ — lógica de dominio (filtrado, mapeo, paginación)
• tools/ — superficie orientada a MCP (descripciones, validación de parámetros, delegación)
• Spring Boot — solo envoltorio de ejecución y transporte

Cada herramienta devuelve un envoltorio consistente ApiResponse<T>:

{ "success": true,  "data": { ... } }
{ "success": false, "errorCode": "REPO_NOT_FOUND", "errorMessage": "..." }

---

Configuración

Propiedad	Variable de entorno	Requerido	Por defecto	Descripción
—	GITHUB_PERSONAL_ACCESS_TOKEN	✅	—	Token de acceso personal de GitHub
—	GITHUB_HOST	❌	github.com	Nombre de host de GitHub (para GitHub Enterprise)
—	GITHUB_READ_ONLY	❌	false	Restringir a operaciones de solo lectura
—	GITHUB_TOOLSETS	❌	all	Lista separada por comas de conjuntos de herramientas a habilitar
—	GITHUB_TOOLS	❌	all	Lista separada por comas de herramientas específicas a habilitar
—	GITHUB_EXCLUDE_TOOLS	❌	none	Lista separada por comas de herramientas a excluir

Creación de un token de acceso personal de GitHub

1. Ve a Configuración de GitHub → Configuración de desarrollador → Tokens de acceso personal
2. Haz clic en "Generar nuevo token (clásico)"
3. Selecciona los siguientes ámbitos:
   • repo — Control total de repositorios privados
   • workflow — Actualizar flujos de trabajo de GitHub Actions
   • read:org — Leer membresía de organizaciones y equipos
   • gist — Crear gists
   • notifications — Acceder a notificaciones
   • read:user — Leer datos del perfil de usuario
4. Genera y copia el token

---

Configuración del cliente

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "github": {
      "url": "http://localhost:8080/sse"
    }
  }
}

En macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

VS Code / GitHub Copilot

Modo URL (si tu cliente lo admite):

{
  "github.copilot.chat.mcp.servers": {
    "github": {
      "url": "http://localhost:8080/sse"
    }
  }
}

Modo comando (clientes solo stdio):

{
  "github.copilot.chat.mcp.servers": {
    "github": {
      "command": "java",
      "args": ["-jar", "/path/to/github-mcp-server-1.0.0.jar"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..."
      }
    }
  }
}

---

Docker

# Build image
docker build -t github-mcp-server:latest .

# Run
docker run --rm -p 8080:8080 \
  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_... \
  github-mcp-server:latest

Si GitHub Enterprise se ejecuta en Docker en el mismo host, usa host.docker.internal:

-e GITHUB_HOST=http://host.docker.internal:3000

---

Ejecutar pruebas

mvn test

---

Estructura del paquete

com.github.mcp
├── GithubMcpApplication.java              @SpringBootApplication
├── config/
│   ├── GitHubProperties.java              @ConfigurationProperties — token, host, readOnly, toolsets
│   └── WebConfig.java                     Web configuration
├── client/
│   ├── GitHubRestClient.java              GET/POST/PATCH/DELETE HTTP gateway; typed exceptions
│   └── GitHubGraphqlClient.java           GraphQL client
├── controller/
│   └── HealthController.java              Health check endpoint (GET /health)
├── exception/
│   ├── GitHubMcpException.java            Base exception
│   └── GlobalExceptionHandler.java        Global error handler
├── dto/
│   ├── common/   ApiResponse · PagedResponse
│   ├── request/  *Request DTOs
│   └── response/ *Response DTOs
├── service/      Interfaces + impl — business logic, error mapping, pagination
└── tools/
    ├── RepositoryTools.java   (11 tools)
    ├── IssueTools.java        (11 tools)
    ├── PullRequestTools.java  (10 tools)
    ├── SearchTools.java       (4 tools)
    └── UserTools.java         (3 tools)

---

Solución de problemas

401 Unauthorized

Problema con el token. Verifica:

1. GITHUB_PERSONAL_ACCESS_TOKEN está configurado correctamente
2. El token no ha expirado
3. El token tiene los ámbitos requeridos (ver Configuración)
4. Para GitHub Enterprise: confirma que GITHUB_HOST está configurado con la URL de tu instancia

REPO_NOT_FOUND / 404 Not Found

El repositorio puede ser privado y el token carece del ámbito repo, o el propietario/nombre es incorrecto.

Tiempos de espera de conexión

El servidor se conecta a api.github.com (o a tu GITHUB_HOST). Asegúrate de que el proceso JVM tenga acceso de red saliente.

Copilot / Claude no puede ver el servidor

1. Confirma que el servidor está en ejecución: curl http://localhost:8080/health
2. Confirma que el endpoint MCP SSE está activo: curl http://localhost:8080/sse
3. Verifica que la URL en la configuración del cliente apunte a http://localhost:8080/sse

---

Agradecimientos

Este proyecto es un port a Java / Spring AI del GitHub MCP Server oficial escrito en Go.

---

Licencia

Licencia MIT — consulta LICENSE para más detalles.