Conectando GitLab MCP ao Claude Code Sem Colocar Seu Token na Configuração

Se você deseja que seu assistente de codificação AI leia problemas do GitLab, revise solicitações de mesclagem ou verifique o status do pipeline, ele precisa de acesso à API.

O zereight/gitlab-mcp fornece exatamente isso através do MCP.

O problema é que a maioria dos exemplos de configuração coloca seu token de acesso pessoal diretamente em um arquivo de configuração JSON.

Eu queria evitar isso.

Em vez disso, esta configuração mantém o token no seu ambiente de shell e permite que a configuração do MCP faça referência a ele.

Mesma meta, mas o segredo não precisa ser colado manualmente na configuração. Isso também torna a rotação do token muito mais fácil.

Este guia percorre toda a configuração, incluindo dois problemas que comumente fazem essa configuração falhar.

Pré-requisitos

Você precisará de:

• Node.js 18.17 ou mais recente
• Uma conta GitLab em gitlab.com ou uma instância GitLab auto-hospedada
• Um cliente MCP. Estou usando o Claude Code aqui, mas a abordagem de configuração geral é portátil.

Passo 1: Crie um Token de Acesso Pessoal

No GitLab, vá para:

Configurações do Usuário > Tokens de Acesso

Crie um novo token de acesso pessoal.

Escolha o escopo com base no que você deseja que o assistente possa fazer:

Defina uma data de expiração.

Certifique-se de copiar o token quando o GitLab o mostrar. Você não poderá visualizar o token novamente mais tarde.

Passo 2: Descubra sua URL da API

O servidor MCP precisa do endpoint da API do GitLab, não da sua URL normal do GitLab.

A URL da API termina com /api/v4:

https://gitlab.com/api/v4
https://gitlab.example.com/api/v4

Para uma instância auto-hospedada, se sua URL do GitLab for:

https://gitlab.example.com

então sua URL da API é:

https://gitlab.example.com/api/v4

Este é um lugar fácil para cometer um erro.

Não use apenas o nome do host e não use a URL do projeto. O servidor precisa do endpoint da API.

Passo 3: Exporte as Variáveis

Adicione ambas as variáveis ao seu perfil de shell.

Para Bash:

~/.bashrc

Para Zsh:

~/.zshrc

Por exemplo:

export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
export GITLAB_API_URL=https://gitlab.example.com/api/v4

O export É Importante

Esta é provavelmente a maneira mais comum de essa configuração falhar.

Sem export, você cria uma variável de shell que existe apenas dentro do shell onde você a definiu.

Com export, você cria uma variável de ambiente que é herdada por processos lançados a partir desse shell.

Essa distinção importa porque os servidores MCP são executados como processos filhos.

Então isso:

FOO=bar
echo $FOO

funciona:

bar

Mas um processo filho não verá FOO a menos que tenha sido exportado:

FOO=bar
bash -c 'echo $FOO'

O resultado é vazio.

Você pode verificar o ambiente a partir de um processo filho sem imprimir o token real:

bash -lic 'echo "token set: ${GITLAB_PERSONAL_ACCESS_TOKEN:+yes}"; echo "url: $GITLAB_API_URL"'

Você quer algo como:

token set: yes
url: https://gitlab.example.com/api/v4

Se a linha do token estiver em branco, ou:

• Você esqueceu export
• Você editou um arquivo de perfil que seu shell não lê
• Você não iniciou um novo shell após alterar o perfil

Passo 4: Confirme se o Token Funciona Antes de Envolver o MCP

Antes de solucionar problemas do MCP, certifique-se de que as credenciais do GitLab funcionem.

Isso leva cerca de dez segundos e pode economizar muita confusão.

Se essa solicitação falhar, o problema é seu token ou URL da API. Nenhuma quantidade de configuração do MCP irá consertar isso.

Execute:

curl -s -H "PRIVATE-TOKEN: $GITLAB_PERSONAL_ACCESS_TOKEN" \
  "$GITLAB_API_URL/user"

Você deve receber seu objeto de usuário do GitLab de volta.

Então verifique se você pode ver os projetos que espera:

curl -s -H "PRIVATE-TOKEN: $GITLAB_PERSONAL_ACCESS_TOKEN" \
  "$GITLAB_API_URL/projects?membership=true&per_page=20"

Observe o id numérico de um projeto que você se importa.

Isso acaba sendo mais confiável do que usar o caminho do projeto em algumas situações, que abordaremos na seção de solução de problemas.

Passo 5: Instale o Servidor

Existem várias maneiras de instalar o servidor.

Usando npm:

npm install -g @zereight/mcp-gitlab

Ou usando Homebrew:

brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
brew install zereight/gitlab-mcp/zereight-mcp-gitlab

Ambas as abordagens lhe dão o binário zereight-mcp-gitlab.

Você também pode pular a instalação global e deixar npx buscá-lo quando iniciar. Isso troca um pouco de tempo de inicialização por sempre obter o pacote atual.

Verifique o que você tem instalado: