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 the options most users need; see the repository environment reference and CLI reference for the exhaustive tables.

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
TOOL_SURFACE	dynamic	Canonical tool catalog selector: dynamic, meta, or individual
META_TOOLS	legacy	Deprecated compatibility selector. true maps to meta, false maps to individual, and dynamic values map to the matching TOOL_SURFACE value when TOOL_SURFACE is absent
CAPABILITY_SURFACE	full	Resource and prompt catalog selector: full keeps the complete catalog; minimal keeps gitlab://workspace/roots plus gitlab://tools, and disables optional resources, prompts, and workflow guides
META_PARAM_SCHEMA	opaque	Meta-tool input-schema strategy: opaque (default), compact (6.5x opaque size), or full (11.9x opaque size). Applies to meta-tool tools/list schemas only
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)
EMBEDDED_RESOURCES	true	Embed canonical gitlab:// MCP resource URIs in get-tool results; set false for clients that do not tolerate duplicate content blocks
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

Dynamic mode (TOOL_SURFACE=dynamic) is the default and lowest-token catalog. It exposes gitlab_find_action and gitlab_execute_action, while the same GitLab actions remain available through the canonical action catalog.

Use TOOL_SURFACE=meta when a client or workflow prefers consolidated domain dispatchers with an action parameter.

See Dynamic toolset for the find/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 plus gitlab://tools for action discovery, and omits optional resources, prompts, and workflow guides. This does not remove action schemas from dynamic discovery: use gitlab_find_action to retrieve exact schemas inline before calling gitlab_execute_action, or read gitlab://tools/{id} for a manifest entry. The default remains full; no schemas-only capability mode is exposed today.

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	Startup/background update timeout (range: 5s–10m)

Admin options

Variable	Default	Description
YOLO_MODE	false	Skip destructive action confirmations (not recommended)
AUTOPILOT	false	Same as YOLO_MODE — skip destructive confirmations
GITLAB_MCP_ALLOWED_IMPORT_DIRS	—	Additional OS path-list-separated directories allowed for local project/group import archives
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
TOOL_SURFACE=dynamic
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
--tool-surface	dynamic	Canonical tool catalog selector: dynamic, meta, or individual
--meta-tools	(unset)	Deprecated compatibility flag. Use --tool-surface=individual instead of --meta-tools=false
--meta-param-schema	opaque	Meta-tool params schema mode: opaque, compact, or full; applies to meta-tool schemas only
--capability-surface	full	Resource and prompt catalog selector: full or minimal; minimal keeps gitlab://workspace/roots and gitlab://tools, and omits optional resources, workflow guides, and prompts
--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
--embedded-resources	true	Embed canonical MCP resource URIs in get-tool results
--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
--http-idle-timeout	0 (disabled)	HTTP server idle connection timeout. Default 0 disables idle closure, so --session-timeout is the effective lifetime; set a positive duration to recycle idle connections sooner
--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	Startup/background update 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.