Configuration

Developer Documentation

For the complete technical reference, see docs/configuration.md in the repository.

GitLab MCP Server is configured through environment variables for stdio mode and CLI flags for HTTP mode. This page covers all configuration options.

Quick orientation

Stdio mode (default) — configure via environment variables or a .env file. This is the mode used by IDE integrations (VS Code, Cursor, Claude Desktop, etc.).

HTTP mode (--http) — configure via CLI flags. Used for shared/remote deployments (Docker, Fly.io, Kubernetes). Jump to HTTP mode flags.

Required variables

This must be set for the server to start in stdio mode:

Variable	Description	Example
GITLAB_TOKEN	Personal Access Token with api scope	glpat-xxxxxxxxxxxxxxxxxxxx

Core options

Variable	Default	Description
GITLAB_URL	https://gitlab.com	GitLab instance base URL. Set this for self-managed instances
GITLAB_SKIP_TLS_VERIFY	false	Skip TLS certificate verification for self-signed certs
META_TOOLS	true	Legacy boolean selector: true for meta-tools or false for individual tools. Use TOOL_SURFACE for dynamic surfaces
TOOL_SURFACE	—	Explicit tool catalog selector: meta, individual, dynamic, dynamic-2, or dynamic-3. When set, it overrides META_TOOLS
CAPABILITY_SURFACE	full	Resource and prompt catalog selector: full keeps the complete catalog; minimal keeps only gitlab://workspace/roots and disables optional resources and prompts
META_PARAM_SCHEMA	opaque	Meta-tool input-schema strategy: opaque (default), compact (~5x), or full (~10x). Per-action schema is discoverable via gitlab://schema/meta/{tool}/{action} when CAPABILITY_SURFACE=full
GITLAB_ENTERPRISE	false	Enable Enterprise/Premium tools in stdio mode. In HTTP mode, --enterprise can force the catalog; otherwise edition is auto-detected per token+URL entry
GITLAB_READ_ONLY	false	Disable all mutating tools (create, update, delete)
GITLAB_SAFE_MODE	false	Return structured JSON preview instead of executing mutating tools (dry-run mode)
EXCLUDE_TOOLS	—	Comma-separated list of tool names to exclude (e.g., gitlab_delete_project,gitlab_admin)
GITLAB_IGNORE_SCOPES	false	Skip automatic PAT scope detection — register all tools regardless of token scopes
LOG_LEVEL	info	Log verbosity: debug, info, warn, error

Tip

Meta-tools mode (META_TOOLS=true) is strongly recommended. It groups tools by domain (e.g., gitlab_issue handles list, get, create, update, delete) which reduces token usage and improves AI tool selection accuracy.

Use TOOL_SURFACE=dynamic for the current lowest-token catalog: only gitlab_search_tools, gitlab_describe_tools, and gitlab_execute_tool are visible, while the same GitLab actions remain available through the canonical action catalog. TOOL_SURFACE=dynamic-3 selects the same current three-tool surface explicitly for pinned configs. Use TOOL_SURFACE=dynamic-2 only when you intentionally want the experimental find/execute variant.

See Dynamic toolset for the search, describe, execute workflow.

For deployments using the dynamic tool surface where resources and prompts dominate initial context, set CAPABILITY_SURFACE=minimal. It keeps gitlab://workspace/roots for project discovery and omits optional resources, meta-schema resources, workflow guides, and prompts. With CAPABILITY_SURFACE=minimal, use gitlab_describe_tools to retrieve dynamic action schemas inline. The default remains full.

Auto-update

Variable	Default	Description
AUTO_UPDATE	true	Auto-update behavior: true (apply on start), check (notify only), false (disabled)
AUTO_UPDATE_REPO	jmrplens/gitlab-mcp-server	GitHub repository for release assets
AUTO_UPDATE_INTERVAL	1h	Periodic check interval (HTTP mode only)
AUTO_UPDATE_TIMEOUT	60s	Pre-start download timeout (range: 5s–10m)

Admin options

Variable	Default	Description
YOLO_MODE	false	Skip destructive action confirmations (not recommended)
RATE_LIMIT_RPS	0	Per-server tools/call rate limit in req/s (0 = disabled)
RATE_LIMIT_BURST	40	Token-bucket burst size when RATE_LIMIT_RPS > 0

Example .env file

.env

# Required
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

# Optional
GITLAB_SKIP_TLS_VERIFY=false
META_TOOLS=true
GITLAB_ENTERPRISE=false
GITLAB_READ_ONLY=false
GITLAB_SAFE_MODE=false
EXCLUDE_TOOLS=
GITLAB_IGNORE_SCOPES=false
LOG_LEVEL=info

# Auto-update
AUTO_UPDATE=true

For self-managed GitLab, add GITLAB_URL=https://gitlab.example.com.

Client configuration

VS Code / Copilot

Create .vscode/mcp.json in your workspace:

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

Secure token configuration using VS Code input variables:

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

Tip

The password: true option masks the token input. VS Code will prompt for it once per session.

Claude Desktop

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

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

Cursor

Create .cursor/mcp.json in your project:

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

Claude Code

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

Set environment variables before launching:

export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Set GITLAB_URL here only for self-managed instances.

Or use a .env file in the working directory.

Continue

Add to ~/.continue/config.yaml (or your workspace .continue/config.yaml):

mcpServers:
  - name: gitlab
    command: /path/to/gitlab-mcp-server
    env:
      GITLAB_TOKEN: glpat-xxxxxxxxxxxxxxxxxxxx

Reload the Continue window after editing the config. See the Continue MCP docs for HTTP-mode and OAuth alternatives.

Windsurf

Edit ~/.codeium/windsurf/mcp_config.json (Cascade → Plugins → Configure):

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

Restart Windsurf or click Refresh in the Plugins panel to pick up changes.

JetBrains AI

JetBrains IDEs (IntelliJ IDEA, GoLand, PyCharm, etc.) with the AI Assistant plugin support MCP servers via Settings → Tools → AI Assistant → Model Context Protocol.

Add a stdio entry pointing at the binary:

• Name: gitlab
• Command: /path/to/gitlab-mcp-server
• Environment variables: GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

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

Alternatively, create .idea/mcp.json in the project root with the same JSON shape used by VS Code / Cursor. Restart the IDE after editing.

HTTP mode flags

When running in HTTP mode (--http), configuration uses CLI flags instead of environment variables:

Flag	Default	Description
--http	false	Enable HTTP transport mode
--http-addr	:8080	Listen address and port
--gitlab-url	—	Fixed GitLab instance URL. Omit to require GITLAB-URL per request
--skip-tls-verify	false	Skip TLS verification
--meta-tools	true	Enable meta-tool mode. Set false for individual tools
--tool-surface	—	Explicit tool catalog selector: meta, individual, dynamic, dynamic-2, or dynamic-3. Overrides --meta-tools
--meta-param-schema	opaque	Meta-tool params schema mode: opaque, compact, or full
--capability-surface	full	Resource and prompt catalog selector: full or minimal
--enterprise	false	Force Enterprise/Premium tools when explicitly set; omit to auto-detect CE/EE per token+URL entry
--read-only	false	Read-only mode
--safe-mode	false	Intercept mutating tools and return a JSON preview instead of executing them
--exclude-tools	—	Comma-separated tool names to exclude
--ignore-scopes	false	Skip PAT scope detection
--max-http-clients	100	Maximum concurrent client sessions
--session-timeout	30m	Idle session timeout
--auto-update	true	Auto-update mode
--auto-update-repo	jmrplens/gitlab-mcp-server	GitHub release repository
--auto-update-interval	1h	Periodic update check interval
--auto-update-timeout	60s	Pre-start download timeout (5s–10m)
--auth-mode	legacy	Authentication mode: legacy or oauth
--oauth-cache-ttl	15m	OAuth token identity cache TTL (1m–2h)
--revalidate-interval	15m	Token re-validation interval; 0 to disable (upper bound: 24h)
--rate-limit-rps	0	Per-server tools/call rate limit in req/s (0 = disabled)
--rate-limit-burst	40	Token-bucket burst size when --rate-limit-rps > 0
--trusted-proxy-header	—	HTTP header with real client IP for rate limiting behind proxies (e.g. Fly-Client-IP, X-Forwarded-For)

General flags (both stdio and HTTP modes):

Flag	Default	Description
--shutdown	false	Terminate all running instances and exit

Example:

# Single GitLab.com instance (fixed URL for all clients; replace for self-managed GitLab)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.com \
  --max-http-clients=200 \
  --session-timeout=1h

# Multi-instance (each client specifies their GitLab URL via GITLAB-URL header)
./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080

Configuration load order

The server loads configuration in the following order (later sources override earlier ones):

1. ~/.gitlab-mcp-server.env — User-level defaults (home directory)
2. .env — Project-level configuration (current working directory)
3. System environment variables — Exported variables in the shell
4. CLI flags — Command-line arguments (highest priority)

Note

In HTTP mode, GITLAB_TOKEN is not loaded from environment variables. Each client provides their own token via the HTTP request. Clients can send a GITLAB-URL header only when the server starts without --gitlab-url.

When --gitlab-url is configured, it is authoritative and client-provided GITLAB-URL values are ignored and logged. Other server policy options, including schema size (--meta-param-schema) and rate limits (--rate-limit-rps, --rate-limit-burst), cannot be overridden per request.

Self-signed certificates

For GitLab instances with self-signed TLS certificates:

GITLAB_SKIP_TLS_VERIFY=true

Caution

Only use this in trusted network environments. It disables certificate verification for all connections to the GitLab instance.

Read-only mode

Enable GITLAB_READ_ONLY=true to restrict the server to read-only operations. All tools that create, update, or delete resources are disabled. This is useful for:

• Audit and compliance environments
• Shared servers where users should only query data
• Tokens with read_api scope

Safe mode

Enable GITLAB_SAFE_MODE=true to intercept mutating tools and return a structured JSON preview of what would be executed, without actually performing the operation. Read-only tools work normally. This is useful for:

• Reviewing operations before execution (dry-run)
• Training environments where you want to see tool behavior
• Debugging tool parameters without side effects

Note

If GITLAB_READ_ONLY=true is also set, it takes precedence — mutating tools are fully disabled rather than previewed.