GitLab模型上下文协议服务器

GitLab MCP Server

Servidor MCP (Model Context Protocol) para GitLab que implementa as tools descritas na documentação oficial do GitLab MCP. Configurável para apontar a uma instalação on-premises (incluindo GitLab Community Edition).

Requisitos

• Python 3.10+
• Instância GitLab com API REST v4 (inclui GitLab CE)

Instalação

cd gitlab-mcp-server
pip install -e .
# ou
pip install -r requirements.txt

Configuração

Defina as variáveis de ambiente (ou crie um .env a partir de .env.example):

Como obter o token (Personal Access Token)

1. No GitLab, faça login e clique no seu avatar (canto superior direito) → Preferences (ou acesse Settings → Access Tokens).
2. No menu lateral, vá em Access Tokens (em algumas versões: Settings → Access Tokens).
3. Crie um novo token:
   • Token name: por exemplo MCP Server ou gitlab-mcp-server.
   • Expiration: escolha uma data ou deixe em branco (algumas instalações não permitem).
   • Scopes: marque pelo menos api (acesso completo à API) ou read_api (somente leitura). Para criar issues, MRs e usar todas as tools, use api.
4. Clique em Create personal access token.
5. Copie o token na hora — ele só é exibido uma vez. O formato costuma ser glpat- seguido de caracteres (GitLab.com e versões recentes) ou uma string longa em instalações mais antigas.
6. Use esse valor em GITLAB_TOKEN no .env ou nas variáveis de ambiente. Nunca commite o token no repositório.

Em instalações on-premises o caminho pode variar: às vezes User Settings → Access Tokens ou Profile → Access Tokens. A documentação oficial está em Personal Access Tokens.

Exemplo para GitLab on-premises:

export GITLAB_URL=https://gitlab.minhaempresa.com
export GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Execução

Instale o pacote (necessário para python -m gitlab_mcp encontrar o módulo):

pip install -e .

Depois execute a partir da pasta do projeto:

python -m gitlab_mcp
# ou
gitlab-mcp

O servidor usa transporte stdio por padrão (compatível com Cursor e outros clientes MCP).

Uso no Cursor

Em Cursor Settings > MCP adicione um servidor com algo como:

{
  "mcpServers": {
    "gitlab": {
      "command": "python",
      "args": ["-m", "gitlab_mcp"],
      "env": {
        "GITLAB_URL": "http://gitlab.minhaempresa.com",
        "GITLAB_TOKEN": "seu_token_aqui"
      }
    }
  }
}

Ajuste command se usar um venv (ex.: path/to/venv/bin/python ou uv run python).

Agente Ollama (script local)

Você pode rodar um agente em linha de comando que usa Ollama como LLM e chama as tools deste servidor MCP. Útil para testar o MCP sem o Cursor ou para automatizar consultas ao GitLab com um modelo local.

Pré-requisitos

• Ollama instalado e em execução
• Um modelo com suporte a tool calling (ex.: qwen2.5:3b, qwen3:8b)

ollama pull qwen2.5:3b

Como rodar o agente

Na raiz do repositório, com o pacote instalado (pip install -e .) e o .env configurado (GITLAB_URL, GITLAB_TOKEN):

# Dependências do agente (além das do servidor)
pip install ollama

# Modelo padrão (qwen2.5:3b)
python scripts/agent_ollama_mcp.py

# Outro modelo
python scripts/agent_ollama_mcp.py qwen2.5:7b
python scripts/agent_ollama_mcp.py qwen3:8b

Se o pacote não estiver instalado, use PYTHONPATH para o Python encontrar o módulo gitlab_mcp:

# Windows (PowerShell)
$env:PYTHONPATH = "src"; python scripts/agent_ollama_mcp.py

# Linux / macOS
PYTHONPATH=src python scripts/agent_ollama_mcp.py

Interface web do agente (agent_web.py)

Interface em chat no navegador que usa Ollama + MCP (mesma lógica do agente em linha de comando). Você escolhe o modelo na página e envia mensagens; as respostas são formatadas em Markdown e as tools usadas aparecem em cada resposta.

Pré-requisitos para a versão web

• Ollama instalado e em execução (serviço na porta 11434)
• Pelo menos um modelo instalado, com suporte a tool calling (ex.: ollama pull qwen2.5:3b)
• Arquivo .env na raiz do projeto com GITLAB_URL e GITLAB_TOKEN (copie de .env.example e preencha)

Como rodar a versão web

Na raiz do repositório (gitlab-mcp-server):

1. Instale o pacote do servidor MCP (necessário para o backend subir o MCP):

   复制

   pip install -e .
   

2. Instale as dependências da interface web:

   复制

   pip install -r scripts/requirements-agent-web.txt
   

3. Inicie o servidor web:

   复制

   python scripts/agent_web.py
   

   O servidor sobe em http://127.0.0.1:8000 (FastAPI + Uvicorn).

4. Abra no navegador: http://127.0.0.1:8000

   • Selecione o modelo no dropdown (lista vinda do Ollama).
   • Digite sua pergunta e envie; o modelo pode chamar as tools do GitLab (issues, projetos, etc.) e a resposta aparece formatada, com "Tools usadas" expandível.

Exemplos de pergunta: "Quais as issues abertas do projeto X?", "Liste os projetos", "Crie uma issue no projeto Y com título Z".

Se o pacote não estiver instalado (só tiver o código), use PYTHONPATH ao rodar o script:

# Windows (PowerShell)
$env:PYTHONPATH = "src"; python scripts/agent_web.py

# Linux / macOS
PYTHONPATH=src python scripts/agent_web.py

Como funciona o agent_web.py

O agent_web.py é um servidor FastAPI que:

1. Serve a UI — GET / devolve o HTML do chat (scripts/agent_web_index.html). O frontend carrega a lista de modelos via GET /api/models (que consulta o Ollama em http://127.0.0.1:11434/api/tags) e envia cada mensagem do usuário para POST /api/chat.

2. Lista modelos — GET /api/models faz uma requisição ao Ollama e retorna { "models": ["nome1", "nome2", ...] }. A combo do chat é preenchida com esses nomes; assim só aparecem modelos realmente instalados (ollama list).

3. Processa o chat — Em POST /api/chat o corpo contém message, history (histórico da conversa) e model. O servidor:

   • Monta a lista de mensagens (histórico + nova mensagem do usuário).
   • Inicia um subprocesso MCP em stdio (python -m gitlab_mcp), na raiz do repositório, com PYTHONPATH=src se necessário.
   • Obtém a lista de tools do MCP e converte cada uma para o formato de tool do Ollama (nome, descrição, parâmetros JSON Schema).
   • Entra no loop do agente:
     • Chama ollama.chat(model=..., messages=..., tools=...).
     • Se a resposta do modelo tiver tool_calls, para cada uma chama session.call_tool(nome, args) no cliente MCP (que fala com o subprocesso) e anexa o resultado como mensagem de role tool.
     • Repete até o modelo devolver uma resposta sem tool_calls; essa resposta é o texto final exibido ao usuário.
   • Retorna content (resposta final), tool_calls (resumo das tools usadas nessa rodada) e history (para o frontend manter o contexto).

4. Tratamento de erros — Exceções (incluindo ExceptionGroup do asyncio) são desembrulhadas e devolvidas como 400/500 com mensagem legível; o frontend exibe "Erro: ..." na bolha do assistente.

Ou seja: a mesma lógica do agent_ollama_mcp.py (Ollama + MCP em loop) roda no backend a cada requisição de chat; a interface web só envia mensagens e exibe respostas (com Markdown renderizado e "Tools usadas" em cada resposta).

Documentação completa (modelos sugeridos, variáveis de ambiente, exemplos): scripts/README-agent-ollama-mcp.md.

Tools disponíveis

• get_mcp_server_version — Versão do servidor MCP
• list_projects — Listar projetos da instância (id, path_with_namespace, web_url, open_issues_count, etc.)
• list_project_issues — Listar issues de um projeto (com paginação automática)
• create_issue / get_issue — Criar e obter issues
• create_merge_request / get_merge_request — Criar e obter merge requests
• get_merge_request_commits / get_merge_request_diffs / get_merge_request_pipelines — Commits, diffs e pipelines do MR
• get_pipeline_jobs — Jobs de um pipeline CI/CD
• create_workitem_note / get_workitem_notes — Comentários em work items (issues)
• search — Busca global (issues, merge_requests, projects, etc.)
• search_labels — Listar labels de projeto ou grupo
• semantic_code_search — Busca semântica de código (não disponível no GitLab CE; retorna mensagem explicativa)

GitLab Community Edition

A maioria das tools usa apenas a REST API v4 e funciona no CE. Work items são mapeados para issues (notas de issue). semantic_code_search é recurso GitLab Duo/Premium/Ultimate; no CE a tool retorna uma mensagem clara de que o recurso não está disponível.

Segurança — antes de publicar no GitHub

• Nunca commite arquivos com credenciais. O .gitignore já ignora:
  • .env (URL e token do GitLab)
  • .vscode/mcp.json (configuração MCP do Cursor com token)
• Use sempre .env.example como modelo (só placeholders). Quem clonar o repositório copia para .env e preenche com os próprios valores.
• Se você já tiver commitado .env ou .vscode/mcp.json no passado, revoque o token no GitLab e crie um novo; o token antigo permanece no histórico do Git.

Licença

MIT.