GitLab

Gestiona proyectos, repositorios, incidencias, archivos e hitos de GitLab mediante la API de GitLab.

GitHub
1
Prueba este MCPPatrocinado

Documentación

MCP Logo

GitLab MCP Server

Servidor MCP para la API de GitLab, que permite la gestión de proyectos, operaciones de archivos y más. Bifurcado de https://github.com/modelcontextprotocol

Tabla de Contenidos

Instalación

NPX (Recomendado)

npx @therealchristhomas/gitlab-mcp-server

Instalación Global

npm install -g @therealchristhomas/gitlab-mcp-server
gitlab-mcp

Características

  • Creación Automática de Ramas: Al crear/actualizar archivos o enviar cambios, las ramas se crean automáticamente si no existen
  • Manejo Integral de Errores: Mensajes de error claros para problemas comunes
  • Preservación del Historial de Git: Las operaciones mantienen un historial de Git adecuado sin forzar el envío
  • Operaciones por Lotes: Soporte para operaciones de archivo único y de múltiples archivos
  • Gestión del Flujo de Trabajo del Proyecto: Gestión de etiquetas e hitos para una mejor organización del proyecto
  • Gestión de Repositorios: Buscar, crear y bifurcar proyectos de GitLab
  • Operaciones de Archivos: Crear, actualizar y recuperar contenidos de archivos
  • Gestión de Ramas: Crear ramas y gestionar la estructura del repositorio
  • Gestión de Incidencias: Crear, listar, actualizar, buscar y comentar incidencias
  • Gestión de Solicitudes de Fusión: Listar, actualizar, fusionar y comentar solicitudes de fusión
  • Gestión de Etiquetas: Crear, actualizar y eliminar etiquetas de proyecto
  • Hitos de Proyecto: Crear, actualizar y eliminar hitos a nivel de proyecto
  • Hitos de Grupo: Crear, actualizar y eliminar hitos a nivel de grupo que abarcan múltiples proyectos

Hitos de Grupo vs Hitos de Proyecto

Este servidor admite tanto hitos de proyecto como hitos de grupo:

Hitos de Proyecto

  • Limitados a un solo proyecto
  • Usan herramientas: list_milestones, create_milestone, update_milestone, delete_milestone
  • Ejemplo: Realizar seguimiento de funciones para el proyecto my-webapp

Hitos de Grupo

  • Abarcan múltiples proyectos dentro de un grupo
  • Usan herramientas: list_group_milestones, create_group_milestone, update_group_milestone, delete_group_milestone
  • Admiten filtrado avanzado con include_ancestors, include_descendants
  • Ejemplo: Realizar seguimiento de un lanzamiento en my-webapp, my-api y my-admin

Ejemplos de Hitos de Grupo

Listar Hitos de Grupo

{
  "group_id": "my-organization",
  "state": "active",
  "include_descendants": true
}

Crear Hito de Grupo

{
  "group_id": "my-organization",
  "title": "Q1 2025 Release",
  "description": "Major feature release including new tools and performance improvements",
  "due_date": "2025-03-31",
  "start_date": "2025-01-01"
}

Búsqueda Avanzada de Hitos de Grupo

{
  "group_id": "my-organization/core",
  "search": "release",
  "include_ancestors": true,
  "updated_after": "2024-01-01T00:00:00Z"
}

Según la GitLab Group Milestones API, los hitos de grupo son ideales para coordinar lanzamientos y funciones en múltiples proyectos de su organización.

Flujo de Trabajo Práctico: Encontrar Grupos y Crear Hitos

Este es un flujo de trabajo típico para trabajar con hitos de grupo:

1. Buscar Grupos

Primero, encuentre el grupo con el que desea trabajar:

{
  "search": "my-organization",
  "owned": true
}

2. Listar Hitos de Grupo Existentes

Compruebe qué hitos ya existen:

{
  "group_id": "my-organization",
  "state": "active"
}

3. Crear un Hito de Grupo

Cree un hito que abarque múltiples proyectos:

{
  "group_id": "my-organization",
  "title": "Q1 2025 Release",
  "description": "Cross-project release including webapp, API, and admin features",
  "due_date": "2025-03-31"
}

Este flujo de trabajo es especialmente útil para organizaciones grandes con múltiples proyectos relacionados bajo el mismo grupo.

Herramientas

Operaciones de Archivos

  1. create_or_update_file

    • Crear o actualizar un solo archivo en un proyecto
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • file_path (cadena): Ruta donde crear/actualizar el archivo
      • content (cadena): Contenido del archivo
      • commit_message (cadena): Mensaje de confirmación
      • branch (cadena): Rama en la que crear/actualizar el archivo
      • previous_path (cadena opcional): Ruta del archivo a mover/renombrar
    • Devuelve: Contenido del archivo y detalles de la confirmación

  2. push_files

    • Enviar múltiples archivos en una sola confirmación
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • branch (cadena): Rama a la que enviar
      • files (matriz): Archivos a enviar, cada uno con file_path y content
      • commit_message (cadena): Mensaje de confirmación
    • Devuelve: Referencia de rama actualizada

  3. get_file_contents

    • Obtener el contenido de un archivo o directorio
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • file_path (cadena): Ruta al archivo/directorio
      • ref (cadena opcional): Rama/etiqueta/confirmación de la que obtener el contenido
    • Devuelve: Contenido del archivo/directorio

Gestión de Repositorios

  1. search_repositories

    • Buscar proyectos de GitLab
    • Entradas:
      • search (cadena): Consulta de búsqueda
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
    • Devuelve: Resultados de búsqueda de proyectos

  2. create_repository

    • Crear un nuevo proyecto de GitLab
    • Entradas:
      • name (cadena): Nombre del proyecto
      • description (cadena opcional): Descripción del proyecto
      • visibility (cadena opcional): 'private', 'internal' o 'public'
      • initialize_with_readme (booleano opcional): Inicializar con README
    • Devuelve: Detalles del proyecto creado

  3. fork_repository

    • Bifurcar un proyecto
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • namespace (cadena opcional): Espacio de nombres al que bifurcar
    • Devuelve: Detalles del proyecto bifurcado

  4. create_branch

    • Crear una nueva rama
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • branch (cadena): Nombre de la nueva rama
      • ref (cadena opcional): Rama/confirmación de origen para la nueva rama
    • Devuelve: Referencia de la rama creada

Operaciones de Grupo

  1. search_groups

    • Buscar grupos de GitLab
    • Entradas:
      • search (cadena): Consulta de búsqueda de grupos
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
      • owned (booleano opcional): Limitar por grupos propiedad del usuario actual
      • min_access_level (número opcional): Nivel de acceso mínimo (10=Invitado, 20=Reportero, 30=Desarrollador, 40=Mantenedor, 50=Propietario)
    • Devuelve: Resultados de búsqueda de grupos

Gestión de Incidencias

  1. create_issue

    • Crear una nueva incidencia
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • title (cadena): Título de la incidencia
      • description (cadena opcional): Descripción de la incidencia
      • assignee_ids (matriz de números opcional): IDs de usuario a asignar
      • labels (matriz de cadenas opcional): Etiquetas a añadir
      • milestone_id (número opcional): ID del hito
    • Devuelve: Detalles de la incidencia creada

  2. list_issues

    • Listar todas las incidencias en un proyecto de GitLab
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • state (cadena opcional): 'opened', 'closed' o 'all'
      • labels (cadena opcional): Lista de nombres de etiquetas separados por comas
      • milestone (cadena opcional): Título del hito
      • assignee_id (número opcional): ID de usuario del asignado
      • author_id (número opcional): ID de usuario del autor
      • search (cadena opcional): Buscar en título y descripción
      • created_after (cadena opcional): Devolver incidencias creadas después de la fecha (ISO 8601)
      • created_before (cadena opcional): Devolver incidencias creadas antes de la fecha (ISO 8601)
      • updated_after (cadena opcional): Devolver incidencias actualizadas después de la fecha (ISO 8601)
      • updated_before (cadena opcional): Devolver incidencias actualizadas antes de la fecha (ISO 8601)
      • sort (cadena opcional): Ordenar incidencias por varios criterios
      • order_by (cadena opcional): 'asc' o 'desc'
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
      • with_labels_details (booleano opcional): Si es true, devuelve más detalles para cada etiqueta. El valor predeterminado es false.
    • Devuelve: Matriz de objetos de incidencia

  3. update_issue

    • Actualizar una incidencia existente en un proyecto de GitLab
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • issue_iid (número): ID interno de la incidencia
      • title (cadena opcional): Nuevo título de la incidencia
      • description (cadena opcional): Nueva descripción de la incidencia
      • state_event (cadena opcional): 'close' o 'reopen'
      • labels (matriz de cadenas opcional): Matriz de nombres de etiquetas
      • assignee_ids (matriz de números opcional): Matriz de IDs de usuario a asignar
      • milestone_id (número opcional): ID del hito a asignar
    • Devuelve: Detalles de la incidencia actualizada

  4. search_issues

    • Buscar incidencias en un proyecto de GitLab
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • search (cadena): Término de búsqueda para título y descripción
      • state (cadena opcional): 'opened', 'closed' o 'all'
      • labels (cadena opcional): Lista de nombres de etiquetas separados por comas
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
    • Devuelve: Matriz de objetos de incidencia coincidentes

  5. add_issue_comment

    • Añadir un comentario a una incidencia en un proyecto de GitLab
    • Entradas:
      • project_id (cadena): ID del proyecto o ruta codificada en URL
      • issue_iid (número): ID interno de la incidencia
      • body (cadena): Contenido del comentario
    • Devuelve: Detalles del comentario creado

Gestión de Solicitudes de Fusión

  1. create_merge_request
  • Crear una nueva solicitud de fusión
  • Entradas:
    • project_id (cadena): ID del proyecto o ruta codificada en URL
    • title (cadena): Título de la MR
    • description (cadena opcional): Descripción de la MR
    • source_branch (cadena): Rama que contiene los cambios
    • target_branch (cadena): Rama en la que fusionar
    • draft (booleano opcional): Crear como MR en borrador
    • allow_collaboration (booleano opcional): Permitir confirmaciones de miembros ascendentes
  • Devuelve: Detalles de la solicitud de fusión creada
  1. list_merge_requests
  • Listar todas las merge requests en un proyecto de GitLab
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • state (string opcional): 'opened', 'closed', 'locked', 'merged' o 'all'
      • target_branch (string opcional): Filtrar por rama de destino
      • source_branch (string opcional): Filtrar por rama de origen
      • labels (string opcional): Lista de nombres de etiquetas separadas por comas
      • milestone (string opcional): Título del hito
      • assignee_id (número opcional): ID de usuario del asignado
      • author_id (número opcional): ID de usuario del autor
      • search (string opcional): Buscar en título y descripción
      • created_after (string opcional): Devolver MRs creadas después de la fecha (ISO 8601)
      • created_before (string opcional): Devolver MRs creadas antes de la fecha (ISO 8601)
      • updated_after (string opcional): Devolver MRs actualizadas después de la fecha (ISO 8601)
      • updated_before (string opcional): Devolver MRs actualizadas antes de la fecha (ISO 8601)
      • sort (string opcional): Ordenar merge requests
      • order_by (string opcional): 'asc' o 'desc'
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
    • Devuelve: Array de objetos de merge request

  1. update_merge_request

    • Actualizar una merge request existente en un proyecto de GitLab
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • merge_request_iid (número): ID interno de la merge request
      • title (string opcional): Nuevo título de la merge request
      • description (string opcional): Nueva descripción de la merge request
      • state_event (string opcional): 'close' o 'reopen'
      • target_branch (string opcional): Nueva rama de destino
      • labels (string[] opcional): Array de nombres de etiquetas
      • assignee_ids (número[] opcional): Array de IDs de usuario a asignar
      • milestone_id (número opcional): ID del hito a asignar
      • remove_source_branch (booleano opcional): Eliminar rama de origen al fusionar
    • Devuelve: Detalles de la merge request actualizada

  2. merge_merge_request

    • Fusionar una merge request en un proyecto de GitLab
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • merge_request_iid (número): ID interno de la merge request
      • merge_commit_message (string opcional): Mensaje personalizado de commit de fusión
      • should_remove_source_branch (booleano opcional): Eliminar rama de origen después de fusionar
      • merge_when_pipeline_succeeds (booleano opcional): Fusionar cuando el pipeline tenga éxito
      • sha (string opcional): SHA que debe coincidir con el HEAD de la rama de origen
    • Devuelve: Detalles de la merge request fusionada

  3. add_merge_request_comment

    • Agregar un comentario a una merge request en un proyecto de GitLab
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • merge_request_iid (número): ID interno de la merge request
      • body (string): Contenido del comentario
    • Devuelve: Detalles del comentario creado

Gestión de Etiquetas

  1. list_labels

    • Listar todas las etiquetas en un proyecto
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
    • Devuelve: Array de objetos de etiqueta

  2. create_label

    • Crear una nueva etiqueta
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • name (string): Nombre de la etiqueta
      • color (string): Color de la etiqueta (código hexadecimal)
      • description (string opcional): Descripción de la etiqueta
      • priority (número opcional): Prioridad de la etiqueta
    • Devuelve: Detalles de la etiqueta creada

  3. update_label

    • Actualizar una etiqueta existente
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • name (string): Nombre actual de la etiqueta
      • new_name (string opcional): Nuevo nombre de la etiqueta
      • color (string opcional): Nuevo color de la etiqueta
      • description (string opcional): Nueva descripción de la etiqueta
      • priority (número opcional): Nueva prioridad de la etiqueta
    • Devuelve: Detalles de la etiqueta actualizada

  4. delete_label

    • Eliminar una etiqueta
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • name (string): Nombre de la etiqueta a eliminar
    • Devuelve: Confirmación de éxito

Gestión de Hitos

  1. list_milestones

    • Listar todos los hitos en un proyecto
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • state (string opcional): 'active' o 'closed'
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
    • Devuelve: Array de objetos de hito

  2. create_milestone

    • Crear un nuevo hito
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • title (string): Título del hito
      • description (string opcional): Descripción del hito
      • due_date (string opcional): Fecha de vencimiento (YYYY-MM-DD)
      • start_date (string opcional): Fecha de inicio (YYYY-MM-DD)
    • Devuelve: Detalles del hito creado

  3. update_milestone

    • Actualizar un hito existente
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • milestone_id (número): ID del hito
      • title (string opcional): Nuevo título
      • description (string opcional): Nueva descripción
      • due_date (string opcional): Nueva fecha de vencimiento
      • start_date (string opcional): Nueva fecha de inicio
      • state_event (string opcional): 'close' o 'activate'
    • Devuelve: Detalles del hito actualizado

  4. delete_milestone

    • Eliminar un hito
    • Entradas:
      • project_id (string): ID del proyecto o ruta codificada en URL
      • milestone_id (número): ID del hito a eliminar
    • Devuelve: Confirmación de éxito

  5. list_group_milestones

    • Listar todos los hitos en un grupo de GitLab
    • Entradas:
      • group_id (string): ID del grupo o ruta codificada en URL
      • state (string opcional): 'active' o 'closed'
      • title (string opcional): Filtrar por título de hito (sensible a mayúsculas)
      • search (string opcional): Buscar en título o descripción
      • search_title (string opcional): Buscar solo en título
      • include_ancestors (booleano opcional): Incluir hitos del grupo padre
      • include_descendants (booleano opcional): Incluir hitos de subgrupos
      • updated_before (string opcional): Filtrar por fecha de actualización (ISO 8601)
      • updated_after (string opcional): Filtrar por fecha de actualización (ISO 8601)
      • containing_date (string opcional): Hitos que contienen la fecha dada
      • start_date (string opcional): Filtrar donde due_date >= start_date
      • end_date (string opcional): Filtrar donde start_date <= end_date
      • page (número opcional): Número de página para paginación
      • per_page (número opcional): Resultados por página (predeterminado 20)
    • Devuelve: Array de objetos de hito de grupo

  6. create_group_milestone

    • Crear un nuevo hito en un grupo de GitLab
    • Entradas:
      • group_id (string): ID del grupo o ruta codificada en URL
      • title (string): Título del hito
      • description (string opcional): Descripción del hito
      • due_date (string opcional): Fecha de vencimiento (YYYY-MM-DD)
      • start_date (string opcional): Fecha de inicio (YYYY-MM-DD)
    • Devuelve: Detalles del hito de grupo creado

  7. update_group_milestone

    • Actualizar un hito existente en un grupo de GitLab
    • Entradas:
      • group_id (string): ID del grupo o ruta codificada en URL
      • milestone_id (número): ID del hito
      • title (string opcional): Nuevo título
      • description (string opcional): Nueva descripción
      • due_date (string opcional): Nueva fecha de vencimiento
      • start_date (string opcional): Nueva fecha de inicio
      • state_event (string opcional): 'close' o 'activate'
    • Devuelve: Detalles del hito de grupo actualizado

  8. delete_group_milestone

    • Eliminar un hito de un grupo de GitLab
    • Entradas:
      • group_id (string): ID del grupo o ruta codificada en URL
      • milestone_id (número): ID del hito a eliminar
    • Devuelve: Confirmación de éxito

Configuración

Token de Acceso Personal

Crea un Token de Acceso Personal de GitLab con los permisos adecuados:

  • Ve a Configuración de Usuario > Tokens de Acceso en GitLab
  • Selecciona los ámbitos requeridos:
    • api para acceso completo a la API
    • read_api para acceso de solo lectura
    • read_repository y write_repository para operaciones de repositorio
  • Crea el token y guárdalo de forma segura

Uso con Claude Desktop

Agrega lo siguiente a tu claude_desktop_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@therealchristhomas/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Uso con Cursor/VSCode/Winsurf

Agrega lo siguiente a tu configuración de MCP:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@therealchristhomas/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Nota: Reemplaza <YOUR_TOKEN> con tu Token de Acceso Personal de GitLab real. También reemplaza con la URL de tu API de GitLab si no estás usando gitlab.com

Variables de Entorno

  • GITLAB_PERSONAL_ACCESS_TOKEN: Tu token de acceso personal de GitLab (requerido)
  • GITLAB_API_URL: URL base para la API de GitLab (opcional, predeterminado a https://gitlab.com/api/v4)

Para instancias de GitLab autoalojadas, actualiza el GITLAB_API_URL para apuntar a tu instancia:

"GITLAB_API_URL": "https://your-gitlab-instance.com/api/v4"

Desarrollo

Compilación

npm run build

Modo de Desarrollo

npm run dev

Modo de Observación

npm run watch

Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.