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.

Required variables

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

Variable	Description	Example
GITLAB_URL	GitLab instance base URL	https://gitlab.example.com
GITLAB_TOKEN	Personal Access Token with api scope	glpat-xxxxxxxxxxxxxxxxxxxx

Core options

Variable	Default	Description
GITLAB_SKIP_TLS_VERIFY	false	Skip TLS certificate verification for self-signed certs
META_TOOLS	true	Enable meta-tool mode (42 domain tools instead of 1000+ individual tools)
GITLAB_ENTERPRISE	false	Enable Enterprise/Premium tools (35 individual + 15 meta-tools) for GitLab Premium/Ultimate
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)
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.

Optional components

These control which MCP capabilities are enabled:

Variable	Default	Description
ENABLE_ANALYSIS_TOOLS	true	Enable 11 AI-powered analysis tools (requires MCP sampling)
ENABLE_ELICITATION	true	Enable interactive creation wizards (project, issue, MR)
ENABLE_RESOURCES	true	Enable 24 MCP resources for read-only data access
ENABLE_PROMPTS	true	Enable 38 MCP prompt templates

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)

Admin options

Variable	Default	Description
YOLO_MODE	false	Skip destructive action confirmations (not recommended)

Example .env file

.env

# Required
GITLAB_URL=https://gitlab.example.com
GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx

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

# Optional components
ENABLE_ANALYSIS_TOOLS=true
ENABLE_ELICITATION=true
ENABLE_RESOURCES=true
ENABLE_PROMPTS=true

# Auto-update
AUTO_UPDATE=true

Client configuration

VS Code / Copilot

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "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_URL": "https://gitlab.example.com",
        "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_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gitlab": {
      "command": "/path/to/gitlab-mcp-server",
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Claude Code

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

Set environment variables before launching:

export GITLAB_URL="https://gitlab.example.com"
export GITLAB_TOKEN="glpat-xxxxxxxxxxxxxxxxxxxx"

Or use a .env file in the working directory.

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	—	GitLab instance URL (required)
--skip-tls-verify	false	Skip TLS verification
--meta-tools	true	Enable meta-tool mode
--enterprise	false	Enable Enterprise/Premium tools
--read-only	false	Read-only mode
--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
--auth-mode	legacy	Authentication mode: legacy or oauth
--oauth-cache-ttl	15m	OAuth token identity cache TTL (1m–2h)

General flags (both stdio and HTTP modes):

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

Example:

./gitlab-mcp-server \
  --http \
  --http-addr=0.0.0.0:8080 \
  --gitlab-url=https://gitlab.example.com \
  --max-http-clients=200 \
  --session-timeout=1h

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.

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.