gitlab-ci-mcp

Servidor MCP para GitLab CI/CD. Permite que un agente LLM (Claude Code, Cursor, OpenCode, DevX Agent, etc.) trabaje con pipelines, trabajos, programaciones, ramas, etiquetas, solicitudes de fusión y archivos de repositorio.

Python, FastMCP, transporte stdio.

Funciona con cualquier GitLab: SaaS gitlab.com o autohospedado / on-prem. Diseñado pensando en redes corporativas: manejo configurable de NO_PROXY, alternancia opcional de verificación SSL y alcance por proyecto mediante variables de entorno.

Aspectos destacados del diseño

• Anotaciones de herramientas: cada herramienta lleva readOnlyHint / destructiveHint / idempotentHint / openWorldHint para que los clientes MCP puedan clasificar las operaciones (por ejemplo, pedir confirmación solo en las destructivas como gitlab_merge_mr, gitlab_delete_schedule).

• Salida estructurada en cada herramienta: cada herramienta declara un tipo de retorno TypedDict, por lo que FastMCP genera automáticamente un outputSchema y cada resultado lleva structuredContent junto con un bloque de texto markdown pre-renderizado. Los clientes que pueden renderizar datos estructurados los usan; los agentes que prefieren texto compacto obtienen el markdown. No se necesita el parámetro response_format.

• Errores estructurados: los errores de autenticación, 404, 403, 429 (límite de tasa), 5xx y variables de entorno faltantes se convierten en mensajes ToolError accionables (por ejemplo, "Error de autenticación de GitLab... verifique que GITLAB_TOKEN tenga el alcance api") y se muestran como resultados isError=True.

• Validación de entrada Pydantic: cada argumento tiene restricciones tipadas (rangos, longitudes, literales) expuestas automáticamente como JSON Schema.

• Alcance de proyecto por llamada: cada herramienta acepta un project_path opcional que anula GITLAB_PROJECT_PATH para consultas entre proyectos.

• Paginación: las herramientas de listado devuelven un bloque de pagination con page, total, has_more, next_page y una sugerencia de página siguiente en el pie de página markdown.

• Integración con el contexto MCP: gitlab_pipeline_health y gitlab_get_job_log son async y emiten registros info / eventos report_progress a través del contexto MCP para que los clientes puedan mostrar barras de progreso.

• Recursos MCP: gitlab://project/info y gitlab://project/ci-config reflejan búsquedas comunes para clientes que prefieren el modelo de Recursos sobre las herramientas.

• Gestión del ciclo de vida: las sesiones HTTP de python-gitlab se cierran limpiamente al apagar el servidor mediante un hook de ciclo de vida asynccontextmanager.

• Grep de registros: gitlab_get_job_log acepta grep_pattern + grep_context (líneas circundantes) para filtrar mediante expresiones regulares registros de CI de escala de megabytes sin extraer todo el seguimiento al contexto del agente.

Modelo de subprocesos

FastMCP ejecuta automáticamente herramientas síncronas en un hilo de trabajo (anyio.to_thread.run_sync), por lo que no bloquean el bucle de eventos de asyncio; python-gitlab es una biblioteca síncrona y envolver cada llamada en asyncio.to_thread nosotros mismos sería redundante. Las herramientas que se benefician del contexto MCP (progreso, registros de información) se escriben como async def y envuelven explícitamente las llamadas a python-gitlab con asyncio.to_thread.

Características

23 herramientas que cubren la superficie diaria de CI/CD:

Pipelines gitlab_list_pipelines · gitlab_get_pipeline · gitlab_get_pipeline_jobs · gitlab_get_job_log · gitlab_trigger_pipeline · gitlab_retry_pipeline · gitlab_cancel_pipeline · gitlab_pipeline_health

Programaciones gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule

Ramas y etiquetas gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches

Solicitudes de fusión (Merge Requests) gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr

Repositorio y proyecto gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info

Informe de salud del pipeline

gitlab_pipeline_health devuelve un resumen listo para leer durante 7/30 días:

Last 7d:  96.4%  up   | 27/28 success
Last 30d: 92.1%       | 105/114 success
Last 10:  success success success failed success ...

Útil para guardia / triaje: покажи health master за последние 7 дней.

Instalación

Requiere Python 3.10+.

# via uvx (recommended)
uvx --from gitlab-ci-mcp gitlab-ci-mcp

# or via pip/pipx
pipx install gitlab-ci-mcp

Configuración

Toda la configuración se realiza mediante variables de entorno:

Cada herramienta acepta un argumento opcional project_path que anula GITLAB_PROJECT_PATH por llamada, útil para consultas entre proyectos.

Claude Code

Tutorial completo: docs/claude-code.md — requisitos previos, dos rutas de instalación, configuración de múltiples proyectos, GitLab autohospedado detrás de un proxy corporativo, solución de problemas, desinstalación.

Versión corta:

claude mcp add gitlab uvx --from gitlab-ci-mcp gitlab-ci-mcp \
  --env GITLAB_URL=https://gitlab.example.com \
  --env GITLAB_TOKEN=glpat-xxxxxx \
  --env GITLAB_PROJECT_PATH=my-org/my-repo

O en ~/.claude.json / .mcp.json del proyecto:

{
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "gitlab-ci-mcp", "gitlab-ci-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_PROJECT_PATH": "my-org/my-repo",
        "GITLAB_SSL_VERIFY": "true"
      }
    }
  }
}

Verificar:

claude mcp list
# gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ Connected

Cursor / OpenCode / DevX Agent

La misma idea: apunte la configuración de MCP a uvx --from gitlab-ci-mcp gitlab-ci-mcp con las variables de entorno anteriores. Consulte la sintaxis de configuración MCP de cada herramienta.

Ejemplos de prompts

что сломалось в последнем pipeline master

покажи health master за 7 дней для проекта my-org/other-repo

создай MR из feature/foo в master с title "feat: foo"

покажи содержимое .gitlab-ci.yml из master

Límites de tasa y reutilización de conexiones

GitLab impone un límite de tasa por usuario (típicamente 2000 solicitudes/hora para la API REST, configurable por el administrador; consulte /admin/application_settings/network de su instancia).

• El servidor almacena en caché una sesión HTTP de python-gitlab por project_path, por lo que las llamadas repetidas a la misma herramienta contra el mismo proyecto reutilizan la conexión y no se vuelven a autenticar cada vez.

• Las herramientas de listado tienen como valor predeterminado per_page=20 para mantener una sola llamada dentro de un pequeño número de solicitudes API.

• Si alcanza un 429 Too Many Requests, el manejador de errores devuelve un mensaje accionable: espere e intente de nuevo con un per_page más grande o menos llamadas.

GitLab autohospedado detrás de un proxy corporativo

Cuando su computadora portátil tiene un proxy HTTP local (por ejemplo, http://127.0.0.1:3128 para acceso web corporativo) pero GitLab está en la intranet, el proxy intercepta y elimina las solicitudes internas. Dos opciones:

1. Establezca GITLAB_NO_PROXY_DOMAINS: el servidor los agregará a NO_PROXY al inicio y borrará HTTP_PROXY/HTTPS_PROXY de su propio proceso para que no afecten el tráfico de GitLab.

2. Pase explícitamente HTTP_PROXY="" vacío, etc., en la sección env de MCP.

Desarrollo

git clone https://github.com/mshegolev/gitlab-ci-mcp
cd gitlab-ci-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

Ejecute el servidor directamente (transporte stdio, espera en stdin por mensajes MCP):

GITLAB_URL=... GITLAB_TOKEN=... GITLAB_PROJECT_PATH=... gitlab-ci-mcp

Licencia

MIT: consulte LICENSE.

Agradecimientos

Construido sobre python-gitlab y el SDK de Python para MCP.