Getting Started

Developer Documentation

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

Get up and running with GitLab MCP Server in under 5 minutes.

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.

Download

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 (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

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)
META_TOOLS	No	Legacy boolean selector: true for meta-tools or false for individual tools (default true)
TOOL_SURFACE	No	Explicit tool catalog selector: meta, individual, dynamic, dynamic-2, or dynamic-3
CAPABILITY_SURFACE	No	Resource and prompt catalog selector: full or minimal (default full)
GITLAB_ENTERPRISE	No	true to enable Premium/Ultimate tools (default false)
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 preferred current selector and takes precedence over META_TOOLS when both are set. Use TOOL_SURFACE=meta instead of META_TOOLS=true, TOOL_SURFACE=individual instead of META_TOOLS=false, and TOOL_SURFACE=dynamic, dynamic-2, or dynamic-3 for dynamic surfaces. META_TOOLS remains supported for backward 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

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"
      }
    }
  }
}

Roo Code

Open the Roo Code sidebar → click the MCP servers icon → Edit Global MCP (for global config) or Edit Project MCP (creates .roo/mcp.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/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, enable the Enterprise/Premium catalog with GITLAB_ENTERPRISE=true in stdio mode or --enterprise/auto-detection in HTTP mode. 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 meta-tool mode — instead of registering hundreds of individual tools (up to 1011 on GitLab.com Enterprise/Premium), it consolidates them into 32 domain-level meta-tools (47 on self-managed Enterprise/Premium, 48 on GitLab.com Enterprise/Premium with Orbit) that cover 100% of the functionality.

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_search_tools, gitlab_describe_tools, and gitlab_execute_tool, backed by the same canonical GitLab action catalog. TOOL_SURFACE=dynamic-3 explicitly selects that same three-tool surface, and TOOL_SURFACE=dynamic-2 is available as an experimental find/execute variant.

Pair dynamic mode with CAPABILITY_SURFACE=minimal to keep only workspace roots and omit optional resources and prompts when you need the smallest initial MCP context.

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