GitLab

Servidor MCP mcp-gitlab (Português)

Um servidor de integração com GitLab construído sobre o framework fastmcp, fornecendo várias ferramentas de API RESTful do GitLab. Suporta integração com Claude, Smithery e outras plataformas.

Recursos

GitlabSearchUserProjectsTool: Pesquisar usuários e seus projetos ativos por nome de usuário
GitlabGetUserTasksTool: Obter tarefas pendentes do usuário atual
GitlabSearchProjectDetailsTool: Pesquisar projetos e detalhes
GitlabCreateMRCommentTool: Adicionar comentários a merge requests
GitlabAcceptMRTool: Aceitar e mesclar merge requests
GitlabUpdateMRTool: Atualizar responsável, revisores, título, descrição e etiquetas do merge request
GitlabCreateMRTool: Criar um novo merge request com responsável e revisores
GitlabRawApiTool: Chamar qualquer API do GitLab com parâmetros personalizados

Início Rápido

Modo Stdio (Padrão)

# Install dependencies
bun install

# Build the project
bun run build

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

Modo HTTP Stream (Implantação de 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

Variáveis de Ambiente

# 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

Exemplos de Uso

Uso Direto da API HTTP

Você também pode interagir com o servidor MCP diretamente via requisições 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"]
      }
    }
  }'

Exemplos de Ferramentas

Para exemplos detalhados dos parâmetros de cada ferramenta, veja USAGE.md.

Principais benefícios do modo HTTP Stream com autenticação dinâmica:

Suporte multi-tenant: Uma única instância do servidor pode atender vários usuários
Segurança: Cada requisição usa seu próprio token de autenticação e URL da instância GitLab
Flexibilidade: Tokens e URLs do GitLab podem ser configurados por cliente sem reiniciar o servidor
Suporte a múltiplas instâncias: Conecte-se a diferentes instâncias do GitLab a partir do mesmo servidor

Modos de Transporte

Este servidor suporta dois modos de transporte:

1. Transporte Stdio (Padrão)

Melhor para desenvolvimento local e integração direta com clientes MCP
Usa stdin/stdout para comunicação
Nenhuma configuração de rede necessária

2. Transporte HTTP Stream

Permite a implantação do servidor para acesso remoto
Usa requisições HTTP POST com respostas em streaming
Permite que vários clientes se conectem à mesma instância do servidor
Ideal para implantações em produção
Suporta autenticação dinâmica de token via cabeçalhos HTTP

Ao usar o modo HTTP Stream, os clientes podem se conectar a:

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

Métodos de Autenticação

O modo HTTP Stream suporta várias maneiras de fornecer tokens do GitLab e URLs de instância:

Autenticação por Token:

1. Token Bearer (Recomendado):

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

2. Cabeçalho de Token Privado:

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

3. Cabeçalho Alternativo de Token Privado:

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

4. Cabeçalho Personalizado de Token do GitLab:

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

Configuração da URL da Instância GitLab:

1. Cabeçalho de URL do GitLab (Recomendado):

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

2. Cabeçalhos Alternativos de URL do GitLab:

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. Fallback para Variáveis de Ambiente: Se nenhum token ou URL for fornecido nos cabeçalhos, o servidor usará as variáveis de ambiente GITLAB_TOKEN e GITLAB_API_URL.

Exemplo Completo:

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

Estrutura do Projeto

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

Integração

Cliente Desktop Claude

Modo Stdio (Padrão)

Adicione à sua configuração:

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

Modo HTTP Stream (Implantação de Servidor)

Configuração do Servidor: Primeiro inicie o servidor (observe que tanto GITLAB_TOKEN quanto GITLAB_API_URL são opcionais ao usar cabeçalhos 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

Configuração do Cliente:

Opção 1: Com 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"
      ]
    }
  }
}

Opção 2: Com Cabeçalho 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"
      ]
    }
  }
}

Opção 3: Com URL e Token Dinâmicos do GitLab

{
  "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 usuário pode configurar seu próprio token e URL da instância GitLab na configuração do cliente, permitindo que a mesma instância do servidor atenda vários usuários com diferentes permissões e instâncias do GitLab.

Smithery

Use diretamente na plataforma Smithery:

smithery add @zephyr-mcp/gitlab

Ou pesquise "@zephyr-mcp/gitlab" na interface do Smithery e adicione ao seu espaço de trabalho.

Variáveis de ambiente:

GITLAB_API_URL: URL base da sua API do GitLab (obrigatória para o modo stdio, opcional para o modo httpStream - pode ser fornecida via cabeçalhos HTTP)
GITLAB_TOKEN: Token de acesso para autenticação na API do GitLab (obrigatório para o modo stdio, opcional para o modo httpStream - pode ser fornecido via cabeçalhos HTTP)
MCP_TRANSPORT_TYPE: Tipo de transporte (stdio/httpStream)
MCP_HOST: Endereço de vinculação do servidor para o modo HTTP stream
MCP_PORT: Porta HTTP para o modo HTTP stream
MCP_ENDPOINT: Caminho do endpoint HTTP para o modo HTTP stream

Implantação

Implantação com Docker

O repositório inclui um Dockerfile para implantação 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

Exemplo 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: Ao executar em contêineres Docker, certifique-se de definir MCP_HOST=0.0.0.0 para permitir acesso externo. O valor padrão para o transporte httpStream já é 0.0.0.0, mas defini-lo explicitamente garante compatibilidade.

Implantação 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

Gerenciador de Processos (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

GitLab

Documentação

Servidor MCP mcp-gitlab (Português)

Recursos

Início Rápido

Modo Stdio (Padrão)

Modo HTTP Stream (Implantação de Servidor)

Variáveis de Ambiente

Exemplos de Uso

Uso Direto da API HTTP

Exemplos de Ferramentas

Modos de Transporte

1. Transporte Stdio (Padrão)

2. Transporte HTTP Stream

Métodos de Autenticação

Estrutura do Projeto

Integração

Cliente Desktop Claude

Modo Stdio (Padrão)

Modo HTTP Stream (Implantação de Servidor)

Smithery

Implantação

Implantação com Docker

Exemplo de Docker Compose

Implantação Manual

Gerenciador de Processos (PM2)

Links Relacionados