Getting Started

Developer Documentation

For the complete technical reference, see docs/getting-started.md in the repository.

GitLab MCP Server connects your AI assistant to GitLab in under five minutes. You install the server — as a Docker image, a native binary, or through a one-click button — give it a GitLab Personal Access Token, and register it with an MCP-compatible client such as VS Code, Claude Desktop, Cursor, or Claude Code. This guide covers every install path and how to verify the connection.

GitLab MCP Server exposes over 1,000 GitLab operations — 847 tools on CE, up to 1071 on GitLab.com — through three tool modes (dynamic, meta-tool, and individual), so a single token unlocks the entire GitLab API surface.

Prerequisites

Before you begin, make sure you have:

1. A GitLab instance — GitLab.com, self-hosted CE, or EE
2. A Personal Access Token (PAT) with the api scope
3. An MCP-compatible AI client — VS Code + Copilot, Claude Desktop, Cursor, or Claude Code

Creating a personal access token

1. Go to GitLab → Preferences → Access Tokens
2. Create a new token with the api scope
3. Copy the token — you’ll need it for configuration

Tip

For read-only setups, you can use a token with read_api scope and enable GITLAB_READ_ONLY=true. This disables all mutating tools.

Quick install

Pick one — each path ends with you typing a prompt to your assistant. For the full per-client reference, see Manual configuration below.

One-click buttons

These register a Docker-based server (it auto-pulls the image on first run; you need Docker installed). VS Code prompts for your token; Cursor / LM Studio / Kiro add a YOUR_GITLAB_TOKEN placeholder you replace.

For Claude Desktop, download the .mcpb desktop extension instead — a native one-click install (macOS universal + Windows) with no Docker and the token stored in the OS keychain.

Claude Code (claude mcp add)

Docker (no install — pulls the image on first run):

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest --http=false

One-line installer (native binary)

Installs the binary onto your PATH, then registers it. Updates are handled by the binary’s built-in auto-update (or by Homebrew, which pins its own checksummed formula).

# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex

claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server

Self-managed GitLab? Add --env GITLAB_URL=https://gitlab.example.com (and --env GITLAB_SKIP_TLS_VERIFY=true for self-signed certs).

Prefer a guided flow?

The built-in setup wizard collects your token and configures your client for you — no JSON to edit. Run gitlab-mcp-server --setup after installing the binary.

Download

Prefer to place the binary yourself? Download the latest binary for your platform from the GitHub Releases page:

Platform	Binary
Linux (x86_64)	gitlab-mcp-server-linux-amd64
Linux (ARM64)	gitlab-mcp-server-linux-arm64
macOS (universal)	gitlab-mcp-server-darwin-all
macOS (Intel)	gitlab-mcp-server-darwin-amd64
macOS (Apple Silicon)	gitlab-mcp-server-darwin-arm64
Windows (x86_64)	gitlab-mcp-server-windows-amd64.exe
Windows (ARM64)	gitlab-mcp-server-windows-arm64.exe
Claude Desktop	gitlab-mcp-server.mcpb — see Claude Desktop Extension

Make it executable (Linux/macOS)

chmod +x gitlab-mcp-server-*

Optionally, move it to a directory in your PATH:

sudo mv gitlab-mcp-server-linux-amd64 /usr/local/bin/gitlab-mcp-server

Setup wizard

The easiest way to configure local stdio clients is the built-in setup wizard:

gitlab-mcp-server --setup

The wizard will:

• Prompt for your GitLab URL and token
• Load any existing configuration so you can keep or change previous values
• Configure supported MCP clients
• Write ~/.gitlab-mcp-server.env without placing secrets in client JSON files

Note

The setup wizard configures stdio clients only. It offers Web, TUI, and CLI interfaces. See Setup Wizard for modes, supported clients, advanced options, and reconfiguration behavior.

Install as an Open Plugin (Cursor / Claude Code)

This repository ships an Open Plugins v1.0.0 manifest (.plugin/plugin.json) and referenced MCP config (mcp.json) so the server can be installed in a single step on any conformant host (Cursor, Claude Code, OpenCode):

# Cursor / Claude Code (when supported by your version)
/plugin install jmrplens/gitlab-mcp-server

The plugin uses the published Docker image ghcr.io/jmrplens/gitlab-mcp-server:latest via docker run -i --rm, so you need Docker installed and running. The bundled mcp.json is configured for stdio MCP clients and passes --http=false after the image name to override the Docker image’s HTTP default. Keep that override if you copy the Docker configuration into VS Code or another stdio client; otherwise the container will start an HTTP listener and the client will wait forever for a stdio initialize response.

Required environment

The host must provide these variables before enabling the plugin:

Variable	Required	Description
GITLAB_URL	No	GitLab instance URL. Defaults to https://gitlab.com; set for self-managed instances
GITLAB_TOKEN	Yes	Personal Access Token (glpat-...)
GITLAB_SKIP_TLS_VERIFY	No	true for self-signed certs (default false)
TOOL_SURFACE	No	Canonical tool catalog selector: dynamic, meta, or individual (default dynamic)
META_TOOLS	No	Deprecated compatibility selector: true maps to meta, false maps to individual, and dynamic maps to TOOL_SURFACE=dynamic
CAPABILITY_SURFACE	No	Resource and prompt catalog selector: full or minimal (default full)
GITLAB_TIER	No	GitLab edition: free/ce, premium, or ultimate. When unset, detected from GET /license (fallback free). Replaces the deprecated GITLAB_ENTERPRISE boolean.
GITLAB_READ_ONLY	No	true to disable mutating tools (default false)
GITLAB_SAFE_MODE	No	true to preview mutating tool inputs (default false)
LOG_LEVEL	No	debug, info, warn, error (default info)

TOOL_SURFACE is the canonical selector and takes precedence over META_TOOLS when both are set. Use TOOL_SURFACE=dynamic for the default low-token find/execute surface, TOOL_SURFACE=meta for consolidated domain meta-tools, and TOOL_SURFACE=individual for individual tools. META_TOOLS remains supported for compatibility but should be treated as deprecated in favor of the explicit selector.

Prefer a native binary instead of Docker?

The Open Plugins spec runs every entry in the referenced MCP config automatically, so the bundled config uses Docker stdio for portability. For detached HTTP deployments, do not use a stdio client entry; run the Docker image in HTTP mode and configure the MCP client with type: "http" and a URL such as http://localhost:8080/mcp. See HTTP Server Mode.

If you prefer the native binary, install the plugin, locate the installed gitlab-mcp-server plugin directory from your host’s plugin UI or installation output, and then edit its local mcp.json (commonly under .agents/plugins/gitlab-mcp-server/) to replace the Docker command / args with a path to the platform binary you downloaded from GitHub Releases:

{
  "mcpServers": {
    "gitlab": {
      "command": "/usr/local/bin/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "${GITLAB_TOKEN}"
      }
    }
  }
}

Manual configuration

GITLAB_URL defaults to https://gitlab.com; add it only for self-managed GitLab instances.

If you prefer to configure manually, choose your AI client:

VS Code / Copilot

Create or edit .vscode/mcp.json in your workspace root:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Secure token storage

Use VS Code input variables to avoid storing the token in plain text:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "${input:gitlab-token}"
      }
    }
  }
}

Claude Desktop

Easiest path

Claude Desktop also installs with one click via the .mcpb desktop extension — no JSON editing, token stored in the OS keychain.

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

Add the server using the CLI:

claude mcp add gitlab \
  --transport stdio \
  -- /path/to/gitlab-mcp-server

Then set the required token:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Set GITLAB_URL here only for self-managed instances, or create a .env file in your working directory with the variables above.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

JetBrains

1. Open Settings → Tools → AI Assistant → MCP Servers
2. Click + Add and select stdio
3. Set the command to /path/to/gitlab-mcp-server
4. Add GITLAB_TOKEN = glpat-xxxxxxxxxxxxxxxxxxxx
5. Add GITLAB_URL only for self-managed instances
6. Click OK and restart the IDE

Zed

Edit your Zed settings.json and add:

{
  "context_servers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "args": [],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Kiro

Create or edit .kiro/mcp.json in your project root:

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "args": [],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cline

Open the Cline sidebar → click the MCP servers icon → Edit Global MCP, or edit the settings file directly:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Using an .env file

Instead of placing secrets in client config files, you can use a .env file:

.env

GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Add GITLAB_URL=https://gitlab.example.com for self-managed GitLab.

The server loads .env from the current working directory automatically. See Configuration for the full load order.

HTTP mode

For team deployments, you can run the server in HTTP mode where each user authenticates with their own token:

./gitlab-mcp-server --http --http-addr=0.0.0.0:8080 --gitlab-url=https://gitlab.com

Each client connects via HTTP and provides their own GitLab token. See HTTP Server Mode for details.

OAuth mode (recommended for production)

For zero-config token management, use OAuth mode. Users authorize through the browser — no token copying or distribution required:

./gitlab-mcp-server --http --gitlab-url=https://gitlab.com --auth-mode=oauth

MCP clients that support OAuth 2.1 (VS Code, Claude Code) discover the authorization server automatically via /.well-known/oauth-protected-resource. See docs/guides/oauth-app-setup.md for creating the required GitLab OAuth Application.

Caution

Clients must be configured with the clientId from the GitLab OAuth Application and api scope. Without clientId, clients fall back to Dynamic Client Registration (DCR) which assigns the mcp scope instead of api, causing most operations to fail. See HTTP Server Mode for per-client examples.

Self-hosted GitLab

If you’re connecting to a self-hosted GitLab instance (Community Edition or Enterprise Edition), the setup is the same — just make sure GITLAB_URL points to your internal instance:

.env

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Self-signed certificates

Many self-hosted instances use self-signed or internal CA certificates. If you see x509: certificate signed by unknown authority errors, add:

.env

GITLAB_SKIP_TLS_VERIFY=true

Caution

Skipping TLS verification disables certificate validation for all GitLab API requests. Only use this for internal instances where you trust the network. For production, configure your system’s CA trust store instead.

Common configurations

Internal HTTPS

.env

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Custom port

.env

GITLAB_URL=https://gitlab.company.com:8443
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

HTTP (dev only)

.env

GITLAB_URL=http://gitlab.local:3000
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

Caution

HTTP connections transmit tokens in plaintext. Only use HTTP for local development instances.

Self-signed cert

.env

GITLAB_URL=https://gitlab.internal.company.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx
GITLAB_SKIP_TLS_VERIFY=true

Both GitLab CE (free) and EE (Premium/Ultimate) are fully supported. For EE-exclusive features like DORA metrics, epics, and vulnerability management, set GITLAB_TIER=premium (or GITLAB_TIER=ultimate) in stdio mode or use --tier=premium/--tier=ultimate in HTTP mode. When unset, the tier is detected from GET /license (fallback free). The legacy boolean GITLAB_ENTERPRISE=true and --enterprise flag are still honored for compatibility but are deprecated. See Configuration for all available options.

Verify the setup

Once configured, open your AI client and ask:

Who am I on GitLab?

The server should return your GitLab user profile, confirming the connection is working. You can also try:

List my assigned merge requests

Show recent pipelines in my-project

If you see results, you’re all set!

Caution

If you get connection errors, check:

• The GITLAB_URL is correct and reachable from your machine
• The token has the api scope
• For self-signed certificates, set GITLAB_SKIP_TLS_VERIFY=true

Understanding meta-tools

By default, the server runs in dynamic find/execute mode with gitlab_find_action and gitlab_execute_action. Set TOOL_SURFACE=meta to use 32 domain-level meta-tools (49 on self-managed Enterprise/Premium, 50 on GitLab.com Enterprise/Premium with Orbit) that cover the same functionality through consolidated domain dispatchers.

For example, instead of separate gitlab_list_issues, gitlab_create_issue, gitlab_close_issue tools, there’s a single gitlab_issue tool with an action parameter:

{
  "tool": "gitlab_issue",
  "arguments": {
    "action": "create",
    "project": "my-group/my-project",
    "title": "Fix login redirect"
  }
}

This is transparent to you — your AI client handles the routing automatically. You just ask naturally: “create an issue for the login bug” and the LLM selects the right meta-tool and action.

Tip

Meta-tools reduce token overhead by 96% while preserving full functionality. See Meta-tools for the complete reference.

For the smallest stable catalog, set TOOL_SURFACE=dynamic. The server exposes only gitlab_find_action and gitlab_execute_action, backed by the same canonical GitLab action catalog.

Pair dynamic mode with CAPABILITY_SURFACE=minimal to keep only workspace roots plus gitlab://tools, and omit optional resources, workflow guides, and prompts when you need the smallest initial MCP context. Dynamic keeps inline schemas through gitlab_find_action.

Common setup questions

What GitLab token scope does GitLab MCP Server need?

GitLab MCP Server needs a Personal Access Token with the api scope for full read and write access to the GitLab REST and GraphQL API. For a read-only setup, create a token with the read_api scope and set GITLAB_READ_ONLY=true, which disables every mutating tool. Create tokens under GitLab → Preferences → Access Tokens.

How do I connect to a self-managed GitLab instance?

Point GITLAB_URL at your instance, for example GITLAB_URL=https://gitlab.example.com. GITLAB_URL defaults to https://gitlab.com, so you set it only for self-managed Community or Enterprise Edition instances. If the instance uses a self-signed or internal CA certificate, also set GITLAB_SKIP_TLS_VERIFY=true to bypass certificate verification on a trusted network.

Which tool mode does GitLab MCP Server use by default?

By default GitLab MCP Server runs in dynamic mode, which exposes only two tools — gitlab_find_action and gitlab_execute_action — to keep the AI client’s context small while still reaching every GitLab operation. Set TOOL_SURFACE=meta for consolidated domain-level meta-tools, or TOOL_SURFACE=individual for one tool per operation.

Why does my AI client fail to connect?

A failed connection usually means GitLab MCP Server cannot reach GitLab or cannot authenticate. Confirm that GITLAB_URL is correct and reachable from your machine, that the token carries the api scope (or read_api in read-only mode) and has not expired, and that self-signed certificates are handled by setting GITLAB_SKIP_TLS_VERIFY=true.

Next steps

• Configuration — Fine-tune environment variables and optional features
• Meta-tools — Understand how tools are organized and discover all available operations
• Architecture — Understand how the server works under the hood
• Tools Reference — Explore all available tools by domain