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

Tool	Description	Parameters
list_merge_requests	List open merge requests in a GitLab project	project (string)
list_issues	List issues in a GitLab project	project (string)
list_pipelines	List recent pipelines in a GitLab project	project (string)

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:

Variable	Description	Example
GITLAB_URL	Base URL of the GitLab API (v4)	https://gitlab.spectrumflow.net/api/v4
GITLAB_TOKEN	GitLab Personal Access Token with api scope	glpat-xxxxxxxxxxxxxxxxxxxx

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

Layer	File	What it tests
Unit	tests/unit/test_tools.py	Tool functions (list_merge_requests, list_issues, list_pipelines) and send_response in isolation with mocked requests.get
Integration (in-process)	tests/integration/test_main_loop.py	main() dispatch loop via injected sys.stdin — routing, error handling, resilience after failures
Integration (subprocess)	tests/integration/test_subprocess.py	Real process spawned via subprocess.Popen — env var validation, tool discovery over the wire, wire protocol error paths

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