GitLab

GitLab MCP Server

Servidor MCP para a API do GitLab, permitindo gerenciamento de projetos, operações de arquivos e muito mais. Bifurcado de https://github.com/modelcontextprotocol

Sumário

Instalação
- NPX (Recomendado)
- Instalação Global
Recursos
Marcos de Grupo vs Marcos de Projeto
- Marcos de Projeto
- Marcos de Grupo
Exemplos de Marcos de Grupo
Fluxo de Trabalho Prático: Encontrando Grupos e Criando Marcos
Ferramentas
Configuração
Variáveis de Ambiente
Desenvolvimento
Licença

Instalação

NPX (Recomendado)

npx @therealchristhomas/gitlab-mcp-server

Instalação Global

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

Recursos

Criação Automática de Branch: Ao criar/atualizar arquivos ou enviar alterações, branches são criados automaticamente se não existirem
Tratamento Abrangente de Erros: Mensagens de erro claras para problemas comuns
Preservação do Histórico do Git: As operações mantêm o histórico adequado do Git sem push forçado
Operações em Lote: Suporte para operações de arquivo único e múltiplos arquivos
Gerenciamento de Fluxo de Trabalho do Projeto: Gerenciamento de labels e marcos para melhor organização do projeto
Gerenciamento de Repositório: Pesquisar, criar e bifurcar projetos do GitLab
Operações de Arquivos: Criar, atualizar e recuperar conteúdos de arquivos
Gerenciamento de Branches: Criar branches e gerenciar a estrutura do repositório
Gerenciamento de Issues: Criar, listar, atualizar, pesquisar e comentar em issues
Gerenciamento de Merge Requests: Listar, atualizar, mesclar e comentar em merge requests
Gerenciamento de Labels: Criar, atualizar e excluir labels do projeto
Marcos de Projeto: Criar, atualizar e excluir marcos em nível de projeto
Marcos de Grupo: Criar, atualizar e excluir marcos em nível de grupo que abrangem vários projetos

Marcos de Grupo vs Marcos de Projeto

Este servidor suporta tanto marcos de projeto quanto marcos de grupo:

Marcos de Projeto

Escopados a um único projeto
Use as ferramentas: list_milestones, create_milestone, update_milestone, delete_milestone
Exemplo: Acompanhar recursos para o projeto my-webapp

Marcos de Grupo

Abrangem vários projetos dentro de um grupo
Use as ferramentas: list_group_milestones, create_group_milestone, update_group_milestone, delete_group_milestone
Suportam filtragem avançada com include_ancestors, include_descendants
Exemplo: Acompanhar um lançamento em my-webapp, my-api e my-admin

Exemplos de Marcos de Grupo

Listar Marcos de Grupo

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

Criar Marco 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"
}

Pesquisa Avançada de Marcos de Grupo

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

Com base na API de Marcos de Grupo do GitLab, os marcos de grupo são ideais para coordenar lançamentos e recursos em vários projetos da sua organização.

Fluxo de Trabalho Prático: Encontrando Grupos e Criando Marcos

Aqui está um fluxo de trabalho típico para trabalhar com marcos de grupo:

1. Pesquisar por Grupos

Primeiro, encontre o grupo com o qual deseja trabalhar:

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

2. Listar Marcos de Grupo Existentes

Verifique quais marcos já existem:

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

3. Criar um Marco de Grupo

Crie um marco que abranja vários projetos:

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

Este fluxo de trabalho é especialmente útil para grandes organizações com vários projetos relacionados sob o mesmo grupo.

Ferramentas

Operações de Arquivos

create_or_update_file
- Criar ou atualizar um único arquivo em um projeto
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - file_path (string): Caminho onde criar/atualizar o arquivo
  - content (string): Conteúdo do arquivo
  - commit_message (string): Mensagem de commit
  - branch (string): Branch onde criar/atualizar o arquivo
  - previous_path (string opcional): Caminho do arquivo para mover/renomear
- Retorna: Conteúdo do arquivo e detalhes do commit
push_files
- Enviar vários arquivos em um único commit
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - branch (string): Branch para enviar
  - files (array): Arquivos para enviar, cada um com file_path e content
  - commit_message (string): Mensagem de commit
- Retorna: Referência da branch atualizada
get_file_contents
- Obter o conteúdo de um arquivo ou diretório
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - file_path (string): Caminho para arquivo/diretório
  - ref (string opcional): Branch/tag/commit de onde obter o conteúdo
- Retorna: Conteúdo do arquivo/diretório

Gerenciamento de Repositório

search_repositories
- Pesquisar projetos do GitLab
- Entradas:
  - search (string): Consulta de pesquisa
  - page (número opcional): Número da página para paginação
  - per_page (número opcional): Resultados por página (padrão 20)
- Retorna: Resultados da pesquisa de projetos
create_repository
- Criar um novo projeto do GitLab
- Entradas:
  - name (string): Nome do projeto
  - description (string opcional): Descrição do projeto
  - visibility (string opcional): 'private', 'internal' ou 'public'
  - initialize_with_readme (booleano opcional): Inicializar com README
- Retorna: Detalhes do projeto criado
fork_repository
- Bifurcar um projeto
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - namespace (string opcional): Namespace para onde bifurcar
- Retorna: Detalhes do projeto bifurcado
create_branch
- Criar uma nova branch
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - branch (string): Nome para a nova branch
  - ref (string opcional): Branch/commit de origem para a nova branch
- Retorna: Referência da branch criada

Operações de Grupo

search_groups
- Pesquisar grupos do GitLab
- Entradas:
  - search (string): Consulta de pesquisa para grupos
  - page (número opcional): Número da página para paginação
  - per_page (número opcional): Resultados por página (padrão 20)
  - owned (booleano opcional): Limitar por grupos pertencentes ao usuário atual
  - min_access_level (número opcional): Nível mínimo de acesso (10=Convidado, 20=Reporter, 30=Desenvolvedor, 40=Mantenedor, 50=Proprietário)
- Retorna: Resultados da pesquisa de grupos

Gerenciamento de Issues

create_issue
- Criar uma nova issue
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - title (string): Título da issue
  - description (string opcional): Descrição da issue
  - assignee_ids (número[] opcional): IDs de usuários para atribuir
  - labels (string[] opcional): Labels para adicionar
  - milestone_id (número opcional): ID do marco
- Retorna: Detalhes da issue criada
list_issues
- Listar todas as issues em um projeto do GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - state (string opcional): 'opened', 'closed' ou 'all'
  - labels (string opcional): Lista de nomes de labels separados por vírgula
  - milestone (string opcional): Título do marco
  - assignee_id (número opcional): ID do usuário responsável
  - author_id (número opcional): ID do usuário autor
  - search (string opcional): Pesquisar no título e na descrição
  - created_after (string opcional): Retornar issues criadas após a data (ISO 8601)
  - created_before (string opcional): Retornar issues criadas antes da data (ISO 8601)
  - updated_after (string opcional): Retornar issues atualizadas após a data (ISO 8601)
  - updated_before (string opcional): Retornar issues atualizadas antes da data (ISO 8601)
  - sort (string opcional): Ordenar issues por vários critérios
  - order_by (string opcional): 'asc' ou 'desc'
  - page (número opcional): Número da página para paginação
  - per_page (número opcional): Resultados por página (padrão 20)
  - with_labels_details (booleano opcional): Se verdadeiro, retorna mais detalhes para cada label. O padrão é falso.
- Retorna: Array de objetos de issue
update_issue
- Atualizar uma issue existente em um projeto do GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - issue_iid (número): ID interno da issue
  - title (string opcional): Novo título da issue
  - description (string opcional): Nova descrição da issue
  - state_event (string opcional): 'close' ou 'reopen'
  - labels (string[] opcional): Array de nomes de labels
  - assignee_ids (número[] opcional): Array de IDs de usuários para atribuir
  - milestone_id (número opcional): ID do marco para atribuir
- Retorna: Detalhes da issue atualizada
search_issues
- Pesquisar issues em um projeto do GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - search (string): Termo de pesquisa para título e descrição
  - state (string opcional): 'opened', 'closed' ou 'all'
  - labels (string opcional): Lista de nomes de labels separados por vírgula
  - page (número opcional): Número da página para paginação
  - per_page (número opcional): Resultados por página (padrão 20)
- Retorna: Array de objetos de issue correspondentes
add_issue_comment
- Adicionar um comentário a uma issue em um projeto do GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - issue_iid (número): ID interno da issue
  - body (string): Conteúdo do comentário
- Retorna: Detalhes do comentário criado

Gerenciamento de Merge Requests

create_merge_request

Criar um novo merge request
Entradas:
- project_id (string): ID do projeto ou caminho codificado em URL
- title (string): Título do MR
- description (string opcional): Descrição do MR
- source_branch (string): Branch contendo as alterações
- target_branch (string): Branch para mesclar
- draft (booleano opcional): Criar como MR de rascunho
- allow_collaboration (booleano opcional): Permitir commits de membros upstream
Retorna: Detalhes do merge request criado

list_merge_requests

Listar todas as merge requests em um projeto GitLab
Entradas:
- project_id (string): ID do projeto ou caminho codificado em URL
- state (string opcional): 'opened', 'closed', 'locked', 'merged' ou 'all'
- target_branch (string opcional): Filtrar por branch de destino
- source_branch (string opcional): Filtrar por branch de origem
- labels (string opcional): Lista de nomes de labels separados por vírgula
- milestone (string opcional): Título do milestone
- assignee_id (number opcional): ID do usuário designado (assignee)
- author_id (number opcional): ID do usuário autor
- search (string opcional): Pesquisar no título e na descrição
- created_after (string opcional): Retornar MRs criadas após a data (ISO 8601)
- created_before (string opcional): Retornar MRs criadas antes da data (ISO 8601)
- updated_after (string opcional): Retornar MRs atualizadas após a data (ISO 8601)
- updated_before (string opcional): Retornar MRs atualizadas antes da data (ISO 8601)
- sort (string opcional): Ordenar merge requests
- order_by (string opcional): 'asc' ou 'desc'
- page (number opcional): Número da página para paginação
- per_page (number opcional): Resultados por página (padrão 20)
Retorna: Array de objetos de merge request

update_merge_request
- Atualizar uma merge request existente em um projeto GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - merge_request_iid (number): ID interno da merge request
  - title (string opcional): Novo título da merge request
  - description (string opcional): Nova descrição da merge request
  - state_event (string opcional): 'close' ou 'reopen'
  - target_branch (string opcional): Nova branch de destino
  - labels (string[] opcional): Array de nomes de labels
  - assignee_ids (number[] opcional): Array de IDs de usuários para atribuir
  - milestone_id (number opcional): ID do milestone para atribuir
  - remove_source_branch (boolean opcional): Remover branch de origem ao mesclar
- Retorna: Detalhes da merge request atualizada
merge_merge_request
- Mesclar uma merge request em um projeto GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - merge_request_iid (number): ID interno da merge request
  - merge_commit_message (string opcional): Mensagem personalizada de commit de merge
  - should_remove_source_branch (boolean opcional): Remover branch de origem após o merge
  - merge_when_pipeline_succeeds (boolean opcional): Mesclar quando o pipeline for bem-sucedido
  - sha (string opcional): SHA que deve corresponder ao HEAD da branch de origem
- Retorna: Detalhes da merge request mesclada
add_merge_request_comment
- Adicionar um comentário a uma merge request em um projeto GitLab
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - merge_request_iid (number): ID interno da merge request
  - body (string): Conteúdo do comentário
- Retorna: Detalhes do comentário criado

Gerenciamento de Labels

list_labels
- Listar todos os labels em um projeto
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - page (number opcional): Número da página para paginação
  - per_page (number opcional): Resultados por página (padrão 20)
- Retorna: Array de objetos de label
create_label
- Criar um novo label
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - name (string): Nome do label
  - color (string): Cor do label (código hex)
  - description (string opcional): Descrição do label
  - priority (number opcional): Prioridade do label
- Retorna: Detalhes do label criado
update_label
- Atualizar um label existente
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - name (string): Nome atual do label
  - new_name (string opcional): Novo nome do label
  - color (string opcional): Nova cor do label
  - description (string opcional): Nova descrição do label
  - priority (number opcional): Nova prioridade do label
- Retorna: Detalhes do label atualizado
delete_label
- Excluir um label
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - name (string): Nome do label a excluir
- Retorna: Confirmação de sucesso

Gerenciamento de Milestones

list_milestones
- Listar todos os milestones em um projeto
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - state (string opcional): 'active' ou 'closed'
  - page (number opcional): Número da página para paginação
  - per_page (number opcional): Resultados por página (padrão 20)
- Retorna: Array de objetos de milestone
create_milestone
- Criar um novo milestone
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - title (string): Título do milestone
  - description (string opcional): Descrição do milestone
  - due_date (string opcional): Data de vencimento (AAAA-MM-DD)
  - start_date (string opcional): Data de início (AAAA-MM-DD)
- Retorna: Detalhes do milestone criado
update_milestone
- Atualizar um milestone existente
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - milestone_id (number): ID do milestone
  - title (string opcional): Novo título
  - description (string opcional): Nova descrição
  - due_date (string opcional): Nova data de vencimento
  - start_date (string opcional): Nova data de início
  - state_event (string opcional): 'close' ou 'activate'
- Retorna: Detalhes do milestone atualizado
delete_milestone
- Excluir um milestone
- Entradas:
  - project_id (string): ID do projeto ou caminho codificado em URL
  - milestone_id (number): ID do milestone a excluir
- Retorna: Confirmação de sucesso
list_group_milestones
- Listar todos os milestones em um grupo GitLab
- Entradas:
  - group_id (string): ID do grupo ou caminho codificado em URL
  - state (string opcional): 'active' ou 'closed'
  - title (string opcional): Filtrar por título do milestone (sensível a maiúsculas/minúsculas)
  - search (string opcional): Pesquisar no título ou na descrição
  - search_title (string opcional): Pesquisar apenas no título
  - include_ancestors (boolean opcional): Incluir milestones do grupo pai
  - include_descendants (boolean opcional): Incluir milestones de subgrupos
  - updated_before (string opcional): Filtrar por data de atualização (ISO 8601)
  - updated_after (string opcional): Filtrar por data de atualização (ISO 8601)
  - containing_date (string opcional): Milestones que contêm a data fornecida
  - start_date (string opcional): Filtrar onde due_date >= start_date
  - end_date (string opcional): Filtrar onde start_date <= end_date
  - page (number opcional): Número da página para paginação
  - per_page (number opcional): Resultados por página (padrão 20)
- Retorna: Array de objetos de milestone do grupo
create_group_milestone
- Criar um novo milestone em um grupo GitLab
- Entradas:
  - group_id (string): ID do grupo ou caminho codificado em URL
  - title (string): Título do milestone
  - description (string opcional): Descrição do milestone
  - due_date (string opcional): Data de vencimento (AAAA-MM-DD)
  - start_date (string opcional): Data de início (AAAA-MM-DD)
- Retorna: Detalhes do milestone do grupo criado
update_group_milestone
- Atualizar um milestone existente em um grupo GitLab
- Entradas:
  - group_id (string): ID do grupo ou caminho codificado em URL
  - milestone_id (number): ID do milestone
  - title (string opcional): Novo título
  - description (string opcional): Nova descrição
  - due_date (string opcional): Nova data de vencimento
  - start_date (string opcional): Nova data de início
  - state_event (string opcional): 'close' ou 'activate'
- Retorna: Detalhes do milestone do grupo atualizado
delete_group_milestone
- Excluir um milestone de um grupo GitLab
- Entradas:
  - group_id (string): ID do grupo ou caminho codificado em URL
  - milestone_id (number): ID do milestone a excluir
- Retorna: Confirmação de sucesso

Configuração

Personal Access Token

Crie um Personal Access Token do GitLab com as permissões adequadas:

Acesse User Settings > Access Tokens no GitLab
Selecione os escopos necessários:
- api para acesso completo à API
- read_api para acesso somente leitura
- read_repository e write_repository para operações de repositório
Crie o token e salve-o com segurança

Uso com Claude Desktop

Adicione o seguinte ao seu 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 com Cursor/VSCode/Winsurf

Adicione o seguinte à sua configuração 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: Substitua <YOUR_TOKEN> pelo seu Personal Access Token real do GitLab. Além disso, substitua pela URL da API do GitLab se você não estiver usando gitlab.com

Variáveis de Ambiente

GITLAB_PERSONAL_ACCESS_TOKEN: Seu personal access token do GitLab (obrigatório)
GITLAB_API_URL: URL base para a API do GitLab (opcional, padrão: https://gitlab.com/api/v4)

Para instâncias GitLab auto-hospedadas, atualize o GITLAB_API_URL para apontar para sua instância:

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

Desenvolvimento

Build

npm run build

Modo de Desenvolvimento

npm run dev

Modo Watch

npm run watch

Licença

Este servidor MCP é licenciado sob a Licença MIT. Isso significa que você é livre para usar, modificar e distribuir o software, sujeito aos termos e condições da Licença MIT. Para mais detalhes, consulte o arquivo LICENSE no repositório do projeto.