GitLab

Un servidor de integración de GitLab que proporciona acceso a las

GitHub
6
Prueba este MCPPatrocinado

Documentación

Versión en chino

Build Status Node Version License

Downloads npm version smithery badge

mcp-gitlab MCP Server (Español)

Un servidor de integración de GitLab construido sobre el framework fastmcp, que proporciona varias herramientas de API RESTful de GitLab. Soporta integración con Claude, Smithery y otras plataformas.

Características

  • GitlabSearchUserProjectsTool: Busca usuarios y sus proyectos activos por nombre de usuario
  • GitlabGetUserTasksTool: Obtiene las tareas pendientes del usuario actual
  • GitlabSearchProjectDetailsTool: Busca proyectos y detalles
  • GitlabCreateMRCommentTool: Añade comentarios a las solicitudes de fusión (merge requests)
  • GitlabAcceptMRTool: Acepta y fusiona solicitudes de fusión
  • GitlabUpdateMRTool: Actualiza el asignado, revisores, título, descripción y etiquetas de la solicitud de fusión
  • GitlabCreateMRTool: Crea una nueva solicitud de fusión con asignado y revisores
  • GitlabRawApiTool: Llama a cualquier API de GitLab con parámetros personalizados

Inicio Rápido

Modo Stdio (Predeterminado)

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with stdio transport (default)
bun run start

Modo HTTP Stream (Despliegue del Servidor)

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with HTTP stream transport
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 bun run start

# Or using command line flag
bun dist/index.js --http-stream

Variables de Entorno

# Required for all modes (optional for httpStream mode - can be provided via HTTP headers)
GITLAB_API_URL=https://your-gitlab-instance.com

# Required for stdio mode, optional for httpStream mode
# (can be provided via HTTP headers in httpStream mode)
GITLAB_TOKEN=your_access_token

# Optional: Provide a mapping from usernames to user IDs (JSON string)
# This can reduce API calls, especially when referencing the same users frequently
# Example: '{"username1": 123, "username2": 456}'
GITLAB_USER_MAPPING={"username1": 123, "username2": 456}

# Optional: Provide a mapping from project names to project IDs (JSON string)
# Project IDs can be numbers or strings (e.g., 'group/project')
# This can reduce API calls and ensure the correct project is used
# Example: '{"project-name-a": 1001, "group/project-b": "group/project-b"}'
GITLAB_PROJECT_MAPPING={"project-name-a": 1001, "group/project-b": "group/project-b"}

# MCP Transport Configuration (Optional)
# Transport type: stdio (default) or httpStream  
MCP_TRANSPORT_TYPE=stdio

# HTTP Stream Configuration (Only used when MCP_TRANSPORT_TYPE=httpStream)
# Server binding address (default: 0.0.0.0 for httpStream, localhost for stdio)
# For Docker deployments, use 0.0.0.0 to allow external access
MCP_HOST=0.0.0.0

# Server port (default: 3000)
MCP_PORT=3000

# API endpoint path (default: /mcp)
MCP_ENDPOINT=/mcp

Ejemplos de Uso

Uso Directo de la API HTTP

También puedes interactuar con el servidor MCP directamente mediante solicitudes HTTP:

# Example: Get user tasks using Bearer token
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-gitlab-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "Gitlab Get User Tasks Tool",
      "arguments": {
        "taskFilterType": "ASSIGNED_MRS",
        "fields": ["id", "title", "source_branch", "target_branch"]
      }
    }
  }'

# Example: Search projects using PRIVATE-TOKEN header
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "PRIVATE-TOKEN: your-gitlab-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "Gitlab Search Project Details Tool",
      "arguments": {
        "projectName": "my-project",
        "fields": ["id", "name", "description", "web_url"]
      }
    }
  }'

# Example: Use dynamic GitLab instance URL with Bearer token
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-gitlab-token" \
  -H "x-gitlab-url: https://gitlab.company.com" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "Gitlab Get User Tasks Tool",
      "arguments": {
        "taskFilterType": "ASSIGNED_MRS",
        "fields": ["id", "title", "source_branch", "target_branch"]
      }
    }
  }'

Ejemplos de Herramientas

Para ejemplos detallados de los parámetros de cada herramienta, consulta USAGE.md.

Beneficios clave del modo HTTP Stream con autenticación dinámica:

  • Soporte multi-tenant: Una única instancia del servidor puede atender a múltiples usuarios
  • Seguridad: Cada solicitud utiliza su propio token de autenticación y URL de instancia de GitLab
  • Flexibilidad: Los tokens y las URL de GitLab se pueden configurar por cliente sin reiniciar el servidor
  • Soporte multi-instancia: Conéctate a diferentes instancias de GitLab desde el mismo servidor

Modos de Transporte

Este servidor soporta dos modos de transporte:

1. Transporte Stdio (Predeterminado)

  • Mejor para desarrollo local e integración directa con clientes MCP
  • Utiliza stdin/stdout para la comunicación
  • No se necesita configuración de red

2. Transporte HTTP Stream

  • Permite el despliegue del servidor para acceso remoto
  • Utiliza solicitudes HTTP POST con respuestas de streaming
  • Permite que múltiples clientes se conecten a la misma instancia del servidor
  • Ideal para despliegues de producción
  • Soporta autenticación dinámica de token mediante cabeceras HTTP

Cuando se usa el modo HTTP Stream, los clientes pueden conectarse a:

POST http://localhost:3000/mcp
Content-Type: application/json

Métodos de Autenticación

El modo HTTP Stream soporta múltiples formas de proporcionar tokens de GitLab y URL de instancia:

Autenticación por Token:

1. Token Bearer (Recomendado):

POST http://localhost:3000/mcp
Content-Type: application/json
Authorization: Bearer your-gitlab-access-token

2. Cabecera de Token Privado:

POST http://localhost:3000/mcp
Content-Type: application/json
PRIVATE-TOKEN: your-gitlab-access-token

3. Cabecera de Token Privado Alternativa:

POST http://localhost:3000/mcp
Content-Type: application/json
private-token: your-gitlab-access-token

4. Cabecera de Token GitLab Personalizada:

POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-token: your-gitlab-access-token

Configuración de la URL de la Instancia GitLab:

1. Cabecera de URL de GitLab (Recomendado):

POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-url: https://gitlab.company.com

2. Cabeceras de URL de GitLab Alternativas:

POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-url: https://gitlab.company.com

POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-api-url: https://gitlab.company.com

5. Recurso a Variables de Entorno: Si no se proporciona token o URL en las cabeceras, el servidor recurrirá a las variables de entorno GITLAB_TOKEN y GITLAB_API_URL.

Ejemplo Completo:

POST http://localhost:3000/mcp
Content-Type: application/json
Authorization: Bearer your-gitlab-access-token
x-gitlab-url: https://gitlab.company.com

Estructura del Proyecto

src/
├── server/
│   └── GitlabMCPServer.ts          # MCP server entry point
├── tools/
│   ├── GitlabAcceptMRTool.ts
│   ├── GitlabCreateMRCommentTool.ts
│   ├── GitlabGetUserTasksTool.ts
│   ├── GitlabRawApiTool.ts
│   ├── GitlabSearchProjectDetailsTool.ts
│   ├── GitlabSearchUserProjectsTool.ts
│   └── gitlab/
│       ├── FieldFilterUtils.ts
│       ├── GitlabApiClient.ts
│       └── GitlabApiTypes.ts
├── utils/
│   ├── is.ts
│   └── sensitive.ts
smithery.json                      # Smithery config
USAGE.md                          # Usage examples
package.json
tsconfig.json

Integración

Cliente de Escritorio Claude

Modo Stdio (Predeterminado)

Añade a tu configuración:

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": ["-y", "@zephyr-mcp/gitlab"]
    }
  }
}

Modo HTTP Stream (Despliegue del Servidor)

Configuración del Servidor: Primero inicia el servidor (ten en cuenta que tanto GITLAB_TOKEN como GITLAB_API_URL son opcionales cuando se usan cabeceras HTTP):

# On your server - no token or URL required in env vars
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 MCP_HOST=0.0.0.0 npx @zephyr-mcp/gitlab

# Or with Docker
docker run -d \
  -p 3000:3000 \
  -e MCP_TRANSPORT_TYPE=httpStream \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3000 \
  gitlab-mcp-server

Configuración del Cliente:

Opción 1: Con Token Bearer (Recomendado)

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-cli",
        "http://your-server:3000/mcp",
        "--header", "Authorization: Bearer your-gitlab-access-token"
      ]
    }
  }
}

Opción 2: Con Cabecera de Token Privado

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-cli",
        "http://your-server:3000/mcp",
        "--header", "PRIVATE-TOKEN: your-gitlab-access-token"
      ]
    }
  }
}

Opción 3: Con URL y Token de GitLab Dinámicos

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-cli",
        "http://your-server:3000/mcp",
        "--header", "Authorization: Bearer your-gitlab-access-token",
        "--header", "x-gitlab-url: https://gitlab.company.com"
      ]
    }
  }
}

Uso Multi-tenant: Cada usuario puede configurar su propio token y URL de instancia de GitLab en su configuración de cliente, lo que permite que la misma instancia del servidor atienda a múltiples usuarios con diferentes permisos e instancias de GitLab.

Smithery

Úsalo directamente en la plataforma Smithery:

smithery add @zephyr-mcp/gitlab

O busca "@zephyr-mcp/gitlab" en la interfaz de Smithery y añádelo a tu espacio de trabajo.

Variables de entorno:

  • GITLAB_API_URL: URL base de tu API de GitLab (requerida para modo stdio, opcional para modo httpStream - se puede proporcionar mediante cabeceras HTTP)
  • GITLAB_TOKEN: Token de acceso para la autenticación de la API de GitLab (requerido para modo stdio, opcional para modo httpStream - se puede proporcionar mediante cabeceras HTTP)
  • MCP_TRANSPORT_TYPE: Tipo de transporte (stdio/httpStream)
  • MCP_HOST: Dirección de enlace del servidor para el modo HTTP stream
  • MCP_PORT: Puerto HTTP para el modo HTTP stream
  • MCP_ENDPOINT: Ruta del endpoint HTTP para el modo HTTP stream

Despliegue

Despliegue con Docker

El repositorio incluye un Dockerfile para un despliegue fácil:

# Build the Docker image
docker build -t gitlab-mcp-server .

# Run with environment variables (both token and URL can be provided via HTTP headers)
docker run -d \
  -p 3000:3000 \
  -e MCP_TRANSPORT_TYPE=httpStream \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3000 \
  gitlab-mcp-server

Ejemplo de Docker Compose

services:
  gitlab-mcp:
    image: node:22.14.0
    container_name: gitlab-mcp
    ports:
      - "3000:3000"
    environment:
      - MCP_TRANSPORT_TYPE=httpStream
      - MCP_HOST=0.0.0.0
      - MCP_PORT=3000
      # Both GITLAB_API_URL and GITLAB_TOKEN are optional when using HTTP headers
      # - GITLAB_API_URL=https://your-gitlab-instance.com
      # - GITLAB_TOKEN=your_gitlab_token
    command: npx -y @zephyr-mcp/gitlab@latest

Importante para Docker: Al ejecutar en contenedores Docker, asegúrate de establecer MCP_HOST=0.0.0.0 para permitir el acceso externo. El valor predeterminado para el transporte httpStream ya es 0.0.0.0, pero establecerlo explícitamente garantiza la compatibilidad.

Despliegue Manual

# Install dependencies and build
npm install
npm run build

# Start the server in HTTP stream mode
export GITLAB_API_URL=https://your-gitlab-instance.com
export GITLAB_TOKEN=your_access_token
export MCP_TRANSPORT_TYPE=httpStream
export MCP_PORT=3000

# Run the server
node dist/index.js

Gestor de Procesos (PM2)

# Install PM2
npm install -g pm2

# Create ecosystem file
cat > ecosystem.config.js << EOF
module.exports = {
  apps: [{
    name: 'gitlab-mcp-server',
    script: 'dist/index.js',
    env: {
      GITLAB_API_URL: 'https://your-gitlab-instance.com',
      GITLAB_TOKEN: 'your_access_token',
      MCP_TRANSPORT_TYPE: 'httpStream',
      MCP_PORT: 3000
    }
  }]
}
EOF

# Start with PM2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

Enlaces Relacionados