GitLab MCP Server

MCP (Model Context Protocol) server that exposes the GitLab REST API as tools for AI agents. It allows models like GitHub Copilot or Claude to interact with GitLab projects, merge requests, issues, pipelines, and more directly from the chat interface.

Table of Contents

• Architecture
• Requirements
• Configuration
• Usage
• Available Tools
  • Users
  • Groups
  • Projects
  • Merge Requests
  • Issues
  • Pipelines
• Local Development
• Project Structure
• Tests

Architecture

The server follows a clean layered architecture:

┌─────────────────────────────────────┐
│            MCP Client               │
│  (Copilot / Claude / any LLM)       │
└──────────────┬──────────────────────┘
               │ stdio (JSON-RPC)
┌──────────────▼──────────────────────┐
│         Infrastructure              │
│  ┌─────────────────────────────┐    │
│  │  MCP Server (index.ts)      │    │
│  │  toolList · toolRouter      │    │
│  │  Domain handlers            │    │
│  └────────────┬────────────────┘    │
│  ┌────────────▼────────────────┐    │
│  │  Controllers (REST adapter)  │    │
│  └────────────┬────────────────┘    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│           Application              │
│  Use Cases (one per operation)      │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│             Domain                  │
│  Interfaces · Types · Errors        │
└──────────────┬──────────────────────┘
               │ fetch (HTTP/HTTPS)
┌──────────────▼──────────────────────┐
│        GitLab REST API              │
└─────────────────────────────────────┘

Tool call flow:

1. The agent invokes a tool (e.g. list_mrs).
2. The MCP Server receives the request via stdio and routes it with toolRouter.
3. The matching handler delegates to the application Use Case.
4. The Use Case calls the Controller, which extends GitLabApiBaseController.
5. The Controller makes the HTTP request to the GitLab API and returns the result.
6. The response is serialized to JSON and returned to the agent.

Requirements

• Node.js >= 18
• A GitLab instance (GitLab.com or self-managed)
• A Personal Access Token with appropriate permissions

Configuration

Authentication and the server URL are configured via environment variables:

Token Scopes

The required scopes depend on the operations you want to perform:

Usage

The server communicates exclusively over stdio using the MCP JSON-RPC protocol. It does not expose any HTTP port.

VS Code integration (GitHub Copilot)

Add the following entry to your VS Code MCP configuration file (.vscode/mcp.json or the global mcp.json in your user settings folder):

{
  "servers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server@latest"],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Desktop integration

In claude_desktop_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server@latest"],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

For self-managed GitLab instances

{
  "servers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp-server@latest"],
      "env": {
        "GITLAB_URL": "https://gitlab.mycompany.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Available Tools

Users

Groups

Projects

Merge Requests

Issues

Pipelines

Local Development

# Clone the repository
git clone https://github.com/yourusername/gitlab-mcp-server.git
cd gitlab-mcp-server

# Install dependencies
npm install

# Run in development mode
GITLAB_URL=https://gitlab.com GITLAB_TOKEN=glpat-xxx npm run dev

# Build
npm run build

Project Structure

gitlab-mcp/
├── src/
│   ├── index.ts                        # Entry point: initializes the MCP server
│   ├── domain/                        # Domain layer (interfaces, types, errors)
│   │   ├── config/                    # GitLabApiConfig
│   │   ├── errors/                    # GitLabAPIError, GitLabErrorType
│   │   └── <domain>/                  # Domain-specific types (project, merge-request, issue, etc.)
│   ├── application/
│   │   ├── use-cases/                 # One Use Case per business operation
│   │   │   ├── project/               # ListProjects, GetProject, etc.
│   │   │   ├── merge-request/         # ListMRs, CreateMR, etc.
│   │   │   ├── issue/                 # ListIssues, CreateIssue, etc.
│   │   │   ├── pipeline/              # ListPipelines, TriggerPipeline, etc.
│   │   │   ├── user/                  # GetCurrentUser, ListUsers
│   │   │   └── group/                 # ListGroups, ListGroupMembers
│   │   └── services/                  # Service interfaces
│   └── infrastructure/
│       ├── controllers/               # HTTP adapters to the GitLab API
│       │   ├── gitlabApiBaseController.ts  # fetch + auth + error handling
│       │   └── <domain>Controller.ts
│       ├── mcp/
│       │   ├── container.ts           # IoC: instantiates all use cases and controllers
│       │   ├── toolList.ts            # JSON schema definition for every tool
│       │   ├── toolRouter.ts          # Routes tool names to the right handler
│       │   └── handlers/              # One handler per domain
│       └── utils/                     # withErrorHandling, classifyHttpError
├── tests/                             # Unit tests (Vitest)
├── package.json
├── tsconfig.json
└── vitest.config.ts

Tests

# Run all tests once
npm test

# Watch mode
npm run test:watch

# Visual UI in the browser
npm run test:ui

License

MIT License - see LICENSE file for details.