gitlab-agent-mcp

gitlab-agent-mcp is an MCP server that enables AI assistants to understand GitLab repositories through targeted source code discovery and analysis.

Table of contents:

• Overview
• Architecture
• Getting Started
  • Requirements
  • Configuration
  • Running
  • Docker
• Claude Code Integration

Overview

The project was designed to answer repository-specific questions without requiring:

• Model fine-tuning
• RAG pipelines
• Embedding generation
• Vector databases
• Repository indexing jobs

<b>Instead, the system performs on-demand repository analysis using GitLab's native search capabilities combined with specialized AI agents.</b>

Goals

• Provide repository-aware answers using the latest source code directly from GitLab.
• Reduce operational complexity by eliminating vector databases and embedding pipelines.
• Avoid model fine-tuning for every repository or project.
• Minimize token usage by retrieving only relevant files instead of loading the entire repository.
• Enable AI assistants to understand implementation details, architecture, and code relationships.
• Keep repository knowledge up to date without reindexing or retraining.

What It Can Do

• Locate relevant source code from natural language questions.
• Discover implementation examples.
• Explain relationships between files and components.
• Summarize repository architecture.
• Identify important classes, functions, and modules.
• Provide contextual information to MCP-compatible AI assistants.

Architecture

<img src="./assets/gitlab_agent_mcp.png" width="800"> <br/><br/>

The repository analysis workflow is built using three specialized AI agents:

1. Repository Discovery Agent

Responsible for understanding the developer's question and generating relevant source code search keywords.

Input:

• Developer question

Output:

• Search keywords

Example:

Question/Instruction:
Implement JWT functionality and make the project with id = 6358 as a reference

Keywords:
JWT
login
token

You can find the <b>Project ID</b> on the main page of the project.

<img src="./assets/gitlab_com_project_id.png" width="500"> <br/><br/>

2. Code Relevance Agent

Responsible for analyzing GitLab search results and selecting the most relevant files for the given question.

Input:

• Developer question
• GitLab search results

Output:

• Relevant file candidates

3. Repository Analysis Agent

Responsible for analyzing the selected source files and producing a technical summary, important findings, and code references.

Input:

• Developer question
• Source code context

Output:

• Technical summary
• Important files
• Key findings
• Relevant code examples

Getting Started

Requirements:

• Python version 3.13+
• UV https://docs.astral.sh/uv/

Setup UV environment

uv venv
source .venv/bin/activate
uv sync

Configuration

The application is configured using environment variables.

Example:

GITLAB_URL=https://gitlab.com
GITLAB_TOKEN=glxx-NA-xxxxxxxxxxxxxxxxx

OPENAI_USE_TRANSPORT=true
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=xxxxx

DISCOVERY_MODEL=gpt-5.5
RELEVANCE_MODEL=gpt-5.5
ANALYSIS_MODEL=gpt-5.5

MAX_SEARCH_RESULTS=20
MAX_FILES=5
MAX_FILE_CHARS=15000

PORT=8000

GitLab

Variable	Description
GITLAB_URL	GitLab server URL.
GITLAB_TOKEN	Personal Access Token used to access repositories and source code.

LLM Provider

Variable	Description
OPENAI_BASE_URL	Base URL of an OpenAI-compatible API endpoint.
OPENAI_API_KEY	API key used to authenticate requests.
OPENAI_USE_TRANSPORT	Enables custom transport for providers that require non-standard authentication headers.

The project is provider-agnostic and supports any LLM service that exposes an OpenAI-compatible API.

Examples include:

• OpenAI
• Azure OpenAI
• Ollama
• vLLM
• LiteLLM
• OpenRouter
• Local inference gateways
• Internal enterprise AI platforms

Example configurations:

OpenAI

OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_API_KEY=sk-xxxxxxxx

Ollama

OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=dummy

Internal Gateway

OPENAI_BASE_URL=https://llm.company.com/v1
OPENAI_API_KEY=xxxxxxxx

Models

Variable	Description
DISCOVERY_MODEL	Model used by the Repository Discovery Agent.
RELEVANCE_MODEL	Model used by the Code Relevance Agent.
ANALYSIS_MODEL	Model used by the Repository Analysis Agent.

Models can be different or identical depending on deployment requirements.

Repository Analysis Limits

Variable	Description
MAX_SEARCH_RESULTS	Maximum number of GitLab search results retrieved before reranking.
MAX_FILES	Maximum number of files selected for analysis.
MAX_FILE_CHARS	Maximum number of characters loaded from each file.

Server

Variable	Description
PORT	MCP server listening port.

Running

Make sure all required environment variable are set.

python main.py 

Docker

Build image

docker build -t gitlab-agent-mcp .

Running

docker run --rm --env-file .env -p 8000:8000 gitlab-agent-mcp

Test with MCP Inspector:

npx -y @modelcontextprotocol/inspector

<img src="./assets/mcp_inspector.png" width="800"> <br/><br/>

Claude Code Integration

Installing gitlab-agent-mcp to Claude Code

claude mcp add --transport http mcp_server_code_analyzer http://localhost:8000/mcp

Test with Claude Code

<img src="./assets/mcp_claude.png" width="800"> <br/><br/>