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 elaborar releases — em linguagem natural. Um único binário estático (ou um contêiner), 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 decorar.

10.359 tokens de contexto de inicialização por padrão, o mesmo em todos os níveis do GitLab (1.694 com GITLAB_MCP_CAPABILITY_SURFACE=minimal). Duas ferramentas alcançam todo o catálogo; medido com o tokenizador cl100k_base e verificado em CI a cada commit. Como é medido

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

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

Instale em 60 segundos

Escolha uma opção. Cada caminho termina com você digitando um prompt para seu assistente. Cada canal tem um guia completo: Instalação.

Quer ver antes de instalar? O inspetor de navegador faz login com OAuth e chama o endpoint hospedado somente leitura a partir de uma aba do navegador — nada é baixado. Executá-lo você mesmo ainda é a melhor forma de continuar usando.

Instalação com um clique

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

Cada botão registra o servidor baseado em Docker (baixa automaticamente a imagem na primeira execução; você precisa ter o Docker instalado). A linha do Claude Desktop baixa uma extensão de desktop nativa .mcpb (macOS universal, Windows e Linux amd64 e arm64; sem Docker). Abra com o Claude Desktop, ou no Linux use Extensões > Instalar Extensão..., e preencha as configurações. Precisa de um token? Crie um Personal Access Token com o escopo api. GitLab auto-gerenciado? Adicione uma 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

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

# Any platform (npm/pnpm) — downloads only your platform's prebuilt binary
npx -y @jmrp.io/gitlab-mcp-server          # zero install; clients launch it directly
npm install -g @jmrp.io/gitlab-mcp-server  # or install globally (npm)
pnpm add -g @jmrp.io/gitlab-mcp-server     # or globally (pnpm)
# Any platform (Python: uv/pipx/pip) — platform wheel carrying the same native binary
uvx jmrplens-gitlab-mcp-server             # zero install; clients launch it directly
pipx install jmrplens-gitlab-mcp-server    # or install globally (pipx)
pip install jmrplens-gitlab-mcp-server     # or into the active environment (pip)
# Linux wheels need glibc; on musl systems such as Alpine use the Docker image instead
# Any platform (.NET 10 SDK) — a .NET tool whose entry point is the same native binary
dnx gitlab-mcp-server                      # zero install; clients launch it directly
dotnet tool install -g gitlab-mcp-server   # or install globally (dotnet tool)
# 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

Clientes que iniciam servidores com npx, uvx ou dnx não precisam de instalação — basta apontá-los para npx -y @jmrp.io/gitlab-mcp-server, uvx jmrplens-gitlab-mcp-server ou dnx gitlab-mcp-server.

GitLab auto-gerenciado? Adicione --env GITLAB_URL=https://gitlab.example.com (e, para um certificado autoassinado, monte a CA e defina --env SSL_CERT_FILE=/path/to/ca-bundle.crt; GITLAB_MCP_SKIP_TLS_VERIFY=true é a alternativa mais direta, e o modo OAuth a recusa para uma instância não-loopback).

Execute uma vez para verificar a instalação

Iniciado em um terminal, ou clicado duas vezes no Windows, sem GITLAB_TOKEN definido, o binário imprime o que é e o que precisa e aguarda Enter, para que você possa confirmar a instalação antes de configurar qualquer coisa. A configuração em si fica no JSON do seu cliente MCP, abaixo.

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"]

Experimente sem instalar nada (endpoint hospedado)

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

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

O endpoint roda em modo OAuth, então a credencial viaja como Authorization: Bearer — um personal access token do GitLab funciona lá, verificado exatamente como um OAuth, que é o que mantém clientes sem fluxo OAuth (e uso headless) funcionando. Ele viaja por requisição e nunca é armazenado no servidor. Um cliente que fala o fluxo OAuth não precisa de cabeçalho algum: o 401 carrega um desafio RFC 9728 que ele segue para autorizar no navegador. PRIVATE-TOKEN é o cabeçalho do modo legado e não é aceito aqui; a instância é fixada em https://gitlab.com, então GITLAB-URL é ignorado.

Um token read_api é aceito e recebe uma superfície de ferramentas somente leitura — a verificação de escrita é por ação, então uma credencial que não pode quebrar nada é uma forma suportada de usar o endpoint, não uma rejeitada.

Duas páginas facilitam ainda mais. O cartão do servidor lista todo o catálogo sem nenhuma credencial e traz configuração copiável para Claude Code, Cursor e VS Code — incluindo o ID do cliente OAuth que esses clientes precisam. O inspetor de navegador chama o mesmo endpoint somente leitura a partir de uma aba do navegador: faça login com OAuth, escolha uma ferramenta, leia o JSON-RPC bruto que ele retorna — nada instalado.

É a forma mais rápida de experimentar o servidor, e a forma certa de continuar usando é localmente (qualquer opção acima) — por uma razão concreta, 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 stateless na superfície padrão dynamic: POST é o transporte e um GET autenticado responde 405 por design; sem credencial, qualquer método responde 401 carregando o desafio RFC 6750 que um cliente OAuth segue — um curl simples que recebe 401 é o endpoint funcionando, não falhando. https://mcp.jmrp.io/gitlab/health não precisa de credencial e responde 200 com {"status":"ok",…}. Uma implantação HTTP auto-hospedada também pode rodar --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com/mcp (ambos são necessários: OAuth precisa de uma instância fixa, e --public-url é o identificador de recurso RFC 9728 — passe exatamente o URL com que seus clientes estão configurados, pois um cliente descarta metadados que nomeiam um diferente), onde clientes descobrem o GitLab como servidor de autorização através desses metadados e autorizam no navegador em vez de copiar tokens — veja Configuração do App OAuth. É 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.

É um serviço pessoal, executado por uma pessoa e oferecido como está: sem SLA, sem canal de suporte e sem promessa de que não mudará na próxima semana. Não adiciona cota própria — cada chamada gasta os limites do próprio GitLab.com, sob seu próprio token. E ele se atualiza sozinho, normalmente para a versão mais recente, então o que serve nunca é uma versão fixada.

Então é só perguntar: abra seu cliente de IA e tente "Liste meus projetos do GitLab." Veja o guia Começando 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 mesclar?" nas chamadas de API corretas. Você não toca em endpoints, IDs ou JSON.
• A plataforma inteira — mais de 1000 ferramentas. Cobertura ampla do GitLab REST v4 + GraphQL: projetos, branches, tags, releases, merge requests, issues, pipelines, jobs, grupos, usuários, wikis, ambientes, deployments, pacotes, registro de contêineres, runners, feature flags, variáveis de CI/CD, segurança, admin, tokens e 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 todo o catálogo — então cabe na janela de contexto de qualquer cliente. (Pegada de tokens →)
• Seguro por design. Modo somente leitura, modo seguro (pré-visualização dry-run de toda 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 contêiner; 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 GITLAB_MCP_TOOL_SURFACE. O padrão não requer configuração.

As contagens de ferramentas escalam com sua edição do GitLab (GITLAB_MCP_TIER); níveis superiores expõem mais ações. Veja 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 onde recursos dominam o contexto, defina GITLAB_MCP_CAPABILITY_SURFACE=minimal.

Pegada de tokens

Medido com go run ./cmd/audit_tokens/ -footprint contra o catálogo atual. Os totais estimam o contexto de inicialização visível a 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 GITLAB_MCP_META_PARAM_SCHEMA), veja Token Footprint Reference.

Configuração padrão: com GITLAB_MCP_TOOL_SURFACE não definido ou GITLAB_MCP_TOOL_SURFACE=dynamic, GITLAB_MCP_CAPABILITY_SURFACE=full, GITLAB_MCP_META_PARAM_SCHEMA=opaque e GITLAB_MCP_TIER não definidos (detectado, fallback free), o servidor usa a superfície dinâmica find/execute. Use GITLAB_MCP_TOOL_SURFACE=meta apenas quando você explicitamente quiser meta-ferramentas de domínio; use GITLAB_MCP_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, a menos que a coluna Nível diga o contrário. GITLAB_MCP_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, IDEs JetBrains, Zed, Kiro, Cline. Veja a Compatibility Matrix completa.

Avaliação de uso de ferramentas por modelos de IA

O projeto inclui um avaliador automatizado para qualidade MCP voltada a modelos, e atualmente não publica nenhum resultado. Cada figura que esta seção costumava conter foi retirada, incluindo o sucesso agregado de 99,5% com o qual este README liderava.

Eles foram retirados porque a medição não media o que afirmava. Um struct alimentava o estímulo dado ao modelo, o ambiente em que ele agia, o avaliador que o classificava e o relatório ao mesmo tempo, então partes do corpus colocavam a chamada esperada no prompt que o avaliador depois verificava, correções eram feitas a partir de uma chave de respostas fornecida pelo harness, e o avaliador comparava nomes de parâmetros em vez de seus valores. Uma execução não poderia falhar pelas razões que deveria capturar. As tabelas como estavam por último podem ser lidas no commit 4587cbfb3; o relato do que estava errado com elas é mantido em AI Model Evaluation Results.

O substituto está sendo construído como um pacote marcado sob test/e2e/ no harness de ponta a ponta, que já mantém o estímulo, o ambiente e o registro separados. Os números retornam aqui quando esse harness os produzir.

Retirado. A tabela dinâmica CE publicada aqui, atualizada pela última vez a partir de uma execução Docker datada de 20260627-232303, é legível no commit 4587cbfb3 e não é reproduzida porque a medição por trás dela era insustentável.

Documentação

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

FAQ

Compilando 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 compilação cruzada, 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álise ou backend próprio — os dados fluem apenas entre seu cliente MCP e a instância do GitLab que você configura (mais uma verificação opcional de atualização de binário assinado contra GitHub Releases). Seu token é usado somente para autenticar requisições do GitLab e nunca é registrado. Detalhes completos: PRIVACY.md.

Contribuições upstream

Este servidor é construído sobre as APIs REST e GraphQL do GitLab, sobre client-go e sobre o MCP Go SDK. Quando a compilação revela uma lacuna em um deles, a correção vai para o upstream em vez de permanecer como uma solução alternativa aqui, para que todos os outros usuários desses projetos também se beneficiem:

• client-go: campos de resposta que o GitLab envia e que as structs do SDK não modelavam, encontrados ao comparar cada struct com o que um GitLab em execução realmente envia, e correções como um panic ao decodificar uma issue sem id (merge requests).
• GitLab: documentação da API e anotações de resposta corrigidas onde divergiam do que a API envia, uma correção para que uma identidade GPG revogada não verifique mais commits, e adições propostas como cancelar um merge automático (merge requests).
• MCP Go SDK: correções de conformidade de protocolo em torno de cancelamento, negociação de versão de protocolo e o handshake de inicialização (pull requests).

Cada lacuna é rastreada em docs/development/upstream-bugs.md: a issue ou merge request upstream, se já foi mesclada e em qual versão, e a solução alternativa que este servidor carrega até que seja lançada.

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: GitHub é o repositório canônico. Um espelho somente leitura está disponível em GitLab.com para descoberta; por favor, abra contribuições no GitHub.

Mantido por José M. Requena Plens · Página do projeto · Instância hospedada: mcp.jmrp.io/gitlab