# 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](#overview)
- [Architecture](#architecture)
- [Getting Started](#getting-started)
    - [Requirements](#requirements)
    - [Configuration](#configuration)
    - [Running](#running)
    - [Docker](#docker)
- [Claude Code Integration](#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">](https://github.com/telkomdev/gitlab-agent-mcp)
<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:

```text id="c13rqp"
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">](https://github.com/telkomdev/gitlab-agent-mcp)
<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
```shell
uv venv
source .venv/bin/activate
uv sync
```

### Configuration

The application is configured using environment variables.

Example:

```env
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**

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

**Ollama**

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

**Internal Gateway**

```env
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.

```shell
python main.py 
```

### Docker

Build image
```shell
docker build -t gitlab-agent-mcp .
```

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

Test with MCP Inspector:

```shell
npx -y @modelcontextprotocol/inspector
```

[<img src="./assets/mcp_inspector.png" width="800">](https://github.com/telkomdev/gitlab-agent-mcp)
<br/><br/>

## Claude Code Integration

Installing `gitlab-agent-mcp` to Claude Code
```shell
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">](https://github.com/telkomdev/gitlab-agent-mcp)
<br/><br/>