GitLab MCP Server

A Model Context Protocol (MCP) server that exposes GitLab project data as tools consumable by AI assistants (e.g., GitHub Copilot, Claude Desktop).

Tools

The project parameter accepts a GitLab project ID (integer) or URL-encoded namespace/path (e.g., mygroup%2Fmyrepo).

Requirements

• Python 3.8+

Runtime dependencies are listed in requirements.txt and are automatically installed into an isolated virtual environment when you run start_server.sh (see Usage).

To install them manually:

pip install -r requirements.txt

For running tests:

pip install -r requirements-test.txt

Configuration

The server reads configuration from two environment variables:

Export them before starting the server:

export GITLAB_URL=https://gitlab.spectrumflow.net/api/v4
export GITLAB_TOKEN=your-personal-access-token

Usage

Start the server

./start_server.sh

On first run the script will:

1. Create a .venv virtual environment inside the project directory

2. Install the packages from requirements.txt into that venv

3. Launch mcp_server.py using the venv's Python interpreter

Subsequent runs reuse the existing venv and re-run the pip install step (which is a no-op if dependencies are already satisfied), so startup stays fast.

Or run manually (bring your own environment):

python3 mcp_server.py

Protocol

The server implements the Model Context Protocol (MCP) over stdio using JSON-RPC 2.0, which is the standard expected by VS Code Copilot, Claude Desktop, and other MCP clients.

Handshake sequence (performed automatically by MCP clients):

1. Client → initialize

2. Server → initialize result (protocolVersion, capabilities, serverInfo)

3. Client → notifications/initialized (notification — no response)

4. Client → tools/list

5. Server → tools list

Call a tool:

{"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "list_merge_requests", "arguments": {"project": "123"}}}

Response:

{"jsonrpc": "2.0", "id": 3, "result": {"content": [{"type": "text", "text": "[{\"id\": 42, \"title\": \"Fix bug\"}]"}]}}

Error response (e.g. missing parameter):

{"jsonrpc": "2.0", "id": 3, "error": {"code": -32602, "message": "Missing required argument: 'project'"}}

GitLab API failures are returned as results with "isError": true rather than JSON-RPC errors, per the MCP specification.

VS Code / Copilot MCP Configuration

Add to your mcp.json:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server/start_server.sh",
      "env": {
        "GITLAB_URL": "https://gitlab.spectrumflow.net/api/v4",
        "GITLAB_TOKEN": "your-personal-access-token"
      }
    }
  }
}

Testing

The test suite has 58 tests across three layers. No network calls are made — all GitLab HTTP interactions are mocked.

python -m pytest

Run a specific layer:

python -m pytest tests/unit/
python -m pytest tests/integration/

Project Structure

gitlab-mcp-server/
├── mcp_server.py          # MCP server implementation
├── start_server.sh        # Startup script (bootstraps venv automatically)
├── requirements.txt       # Runtime dependencies
├── requirements-test.txt  # Test-only dependencies
├── pytest.ini             # pytest configuration
├── README.md
├── .venv/                 # Auto-created virtual environment (git-ignored)
└── tests/
    ├── conftest.py        # Shared pytest fixtures and env var setup
    ├── unit/
    │   └── test_tools.py  # Unit tests for tool functions
    └── integration/
        ├── test_main_loop.py   # In-process integration tests for main()
        └── test_subprocess.py  # Subprocess integration tests