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