Gitlab MCP Server

GitLab MCP Server

Conecte seu assistente de IA ao GitLab para que ele possa revisar merge requests, fazer triagem de pipelines, gerenciar issues e redigir releases — em linguagem natural. Um único binário estático (ou um container), mais de 1000 ferramentas GitLab sobre a API REST + GraphQL completa, funcionando com Claude, Cursor, VS Code e qualquer cliente MCP.

Você conversa com seu assistente de IA; ele faz o trabalho no GitLab. Sem IDs de projeto, endpoints de API ou JSON para memorizar.

"Revise o merge request !15 — é seguro fazer merge?" · "Por que o último pipeline falhou?" · "Liste issues abertas atribuídas a mim" · "Gere notas de release da v1.0 para a v2.0"

🤖 Usando um assistente de IA? Dê a ele a URL deste repositório e peça para instalar o servidor para o seu cliente. Tudo o que um modelo precisa para fazer isso de forma autônoma — a configuração declarativa por cliente, os one-liners de claude mcp add e os padrões — está em llms.txt (nenhum assistente interativo necessário).

Instale em 60 segundos

Escolha uma opção. Cada caminho termina com você digitando um prompt para o seu assistente.

Instalação com um clique

Cliente	Botão de um clique	Etapa do token
VS Code		solicita que você informe (mascarado)
VS Code Insiders		solicita que você informe (mascarado)
Cursor		edite YOUR_GITLAB_TOKEN
LM Studio		edite YOUR_GITLAB_TOKEN
Kiro		edite YOUR_GITLAB_TOKEN
Claude Desktop		interface de configurações (keychain)

Cada botão registra o servidor baseado em Docker (baixa a imagem automaticamente na primeira execução; você precisa ter o Docker instalado). A linha do Claude Desktop baixa uma extensão de desktop .mcpb nativa (macOS universal + Windows, sem Docker) — abra com o Claude Desktop e preencha as configurações. Precisa de um token? Crie um Personal Access Token com o escopo api. GitLab auto-gerenciado? Adicione a variável de ambiente GITLAB_URL na configuração MCP do seu cliente após a instalação.

Claude Code (claude mcp add)

Docker (sem instalação — baixa a imagem na primeira execução):

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest --http=false

Ou instale o binário nativo primeiro e depois registre-o:

# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (winget)
winget install --id jmrplens.gitlab-mcp-server -e
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server

GitLab auto-gerenciado? Adicione --env GITLAB_URL=https://gitlab.example.com (e --env GITLAB_SKIP_TLS_VERIFY=true para certificados autoassinados).

Configuração guiada (qualquer cliente, sem flags para memorizar)

O binário inclui um assistente de configuração que coleta seu token do GitLab e configura seu cliente MCP para você — ideal se você preferir não editar JSON:

gitlab-mcp-server --setup

Ele detecta automaticamente VS Code, Claude Desktop, Claude Code, Cursor e Windsurf e grava a configuração correta. No Windows, clique duas vezes em .exe para iniciá-lo.

JSON manual (Claude Desktop, Cursor, VS Code, …)

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest", "--http=false"]

Experimente sem instalar nada (endpoint hospedado)

Uma instância pública roda em https://mcp.jmrp.io/gitlab — nada para instalar, nenhuma conta além do seu próprio token do GitLab. Aponte qualquer cliente MCP com suporte a HTTP para ela:

{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp.jmrp.io/gitlab",
      "headers": { "PRIVATE-TOKEN": "glpat-xxxxxxxxxxxx" }
    }
  }
}

PRIVATE-TOKEN é obrigatório e viaja por requisição — nunca é armazenado no servidor. GITLAB-URL é opcional e o padrão é https://gitlab.com; defina-o para alcançar outra instância (ela deve estar acessível pela internet pública).

É a forma mais rápida de experimentar o servidor, e a maneira correta de continuar usando-o é ainda localmente (qualquer opção acima) ou por meio do Smithery — por um motivo concreto, não como aviso: seu token e cada requisição passam pela máquina de outra pessoa. Executá-lo localmente significa que suas credenciais e seu tráfego do GitLab nunca saem do seu computador, o que também o torna a única opção sensata para uma instância privada auto-gerenciada.

O endpoint é HTTP streamable sem estado na superfície padrão dynamic: POST é o transporte, GET nele responde a 405 por design, e https://mcp.jmrp.io/gitlab/health responde a ok. É um dos servidores listados em mcp.jmrp.io, um diretório dos servidores MCP que mantenho, cada um acessível em seu próprio endpoint; https://mcp.jmrp.io/servers.json é a mesma lista para clientes automatizados.

Então é só perguntar: abra seu cliente de IA e tente "Liste meus projetos do GitLab." Consulte o guia de Introdução para detalhes por cliente e mais exemplos de prompts.

Por que este servidor

• 🗣️ GitLab em linguagem natural. A IA traduz "o MR !15 é seguro para merge?" nas chamadas de API corretas. Você não toca em endpoints, IDs ou JSON.
• 🧰 A plataforma inteira — mais de 1000 ferramentas. Ampla cobertura do GitLab REST v4 + GraphQL: projetos, branches, tags, releases, merge requests, issues, pipelines, jobs, grupos, usuários, wikis, ambientes, deployments, pacotes, container registry, runners, feature flags, variáveis de CI/CD, segurança, admin, tokens e muito mais.
• 🪶 Baixo consumo de tokens por padrão. A superfície dinâmica padrão expõe apenas 2 ferramentas (find + execute) enquanto alcança o catálogo completo — então cabe na janela de contexto de qualquer cliente. (Pegada de tokens →)
• ✅ Comprovado com modelos reais. Um avaliador automatizado executa Anthropic, Google, OpenAI e Qwen contra instâncias reais do GitLab: 99,5% de sucesso agregado em milhares de operações. (Resultados →)
• 🔒 Seguro por design. Modo somente leitura, modo seguro (pré-visualização dry-run de cada mutação), opções de TLS para GitLab auto-hospedado e portões contínuos de qualidade/segurança do SonarCloud.
• 🖥️ Roda em qualquer lugar. Um único binário estático ou container; Windows, Linux e macOS; amd64 e arm64; stdio (desktop) e HTTP (remoto).

Superfícies de ferramentas

O servidor pode apresentar o GitLab em três formatos, controlados por TOOL_SURFACE. O padrão não precisa de configuração.

As contagens de ferramentas escalam com sua edição do GitLab (GITLAB_TIER); níveis mais altos expõem mais ações. Consulte Dynamic Toolset e Meta-Tools Reference para o modelo de classificação, proteções de segurança e catálogos completos. Para execuções dinâmicas em que os recursos dominam o contexto, defina CAPABILITY_SURFACE=minimal.

Pegada de tokens

Medido com go run ./cmd/audit_tokens/ -footprint em relação ao catálogo atual. Os totais estimam o contexto de inicialização visível para um cliente MCP: esquemas de ferramentas visíveis mais recursos e prompts compartilhados, usando o tokenizador cl100k_base (codificação GPT-4/GPT-3.5). Para a matriz completa (superfícies meta e individual, todos os modos META_PARAM_SCHEMA), consulte Token Footprint Reference.

Configuração padrão: com TOOL_SURFACE não definido ou TOOL_SURFACE=dynamic, CAPABILITY_SURFACE=full, META_TOOLS não definidos, META_PARAM_SCHEMA=opaque e GITLAB_TIER não definido (detectado, fallback free), o servidor usa a superfície dinâmica find/execute. Use TOOL_SURFACE=meta apenas quando você quiser explicitamente meta-ferramentas de domínio; use TOOL_SURFACE=individual apenas quando seu cliente puder lidar com o catálogo completo de ferramentas.

As linhas usam o catálogo base da Community Edition, exceto quando a coluna Nível indica o contrário. GITLAB_TIER controla quais ações estão disponíveis; níveis superiores expõem mais ferramentas e, portanto, mais ações alcançáveis.

Compatibilidade

Testado com: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline. Consulte a Matriz de Compatibilidade completa.

Avaliação do Uso de Ferramentas por Modelos de IA

O projeto inclui um avaliador automatizado para a qualidade do MCP voltada aos modelos. Ele executa verificações somente de esquema no catálogo de ferramentas ou executa chamadas de ferramentas validadas pelo modelo por meio do MCP contra instâncias Docker GitLab CE ou Enterprise licenciadas com fixtures. Ele avalia se cada modelo escolhe a ação correta, envia parâmetros válidos, se recupera de erros acionáveis do GitLab e respeita as proteções de ações destrutivas — abrangendo Anthropic, Google, OpenAI e Qwen.

Resultado publicado atual: Docker CE dinâmico 20260627-232303.

O conjunto publicado de avaliação de modelos cobre 596 tentativas de tarefas e 2220 operações MCP esperadas. Nos relatórios selecionados, os modelos emitiram 2265 chamadas de ferramentas em 2265 solicitações de modelos, com 99,5% de sucesso final agregado. Consulte Resultados da Avaliação de Modelos de IA para a matriz atual detalhada.

Documentação

A documentação completa está em jmrplens.github.io/gitlab-mcp-server. Use este mapa para a referência de fonte da verdade em uma área específica:

FAQ

Compilação a partir do Código-Fonte

git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build

A imagem de contêiner publicada é ghcr.io/jmrplens/gitlab-mcp-server:latest. Consulte o Guia de Desenvolvimento para cross-compilation, Docker Compose e diretrizes de contribuição.

Política de Privacidade

O servidor é executado inteiramente na sua máquina e não possui telemetria, análises ou backend próprios — os dados fluem apenas entre o seu cliente MCP e a instância do GitLab que você configura (além de uma verificação opcional de atualização de binário assinado contra o GitHub Releases). O seu token é usado apenas para autenticar solicitações ao GitLab e nunca é registrado em logs. Detalhes completos: PRIVACY.md.

Contribuição e Segurança

• Contribuição: consulte CONTRIBUTING.md para diretrizes de desenvolvimento, nomenclatura de branches, convenções de commit e o processo de PR.
• Segurança: consulte SECURITY.md para a política de segurança e relato de vulnerabilidades.
• Código de Conduta: consulte CODE_OF_CONDUCT.md (Contributor Covenant v2.1).

Espelho do repositório: o GitHub é o repositório canônico. Um espelho somente leitura está disponível no GitLab.com para fins de descoberta; por favor, abra contribuições no GitHub.