Setup Wizard

The setup wizard installs and configures GitLab MCP Server for stdio MCP clients. Use it for local developer setups where your AI client starts the server process directly, such as VS Code, Claude Desktop, Claude Code, Cursor, Windsurf, Copilot CLI, OpenCode, Crush, or Zed.

Quick command

Run the wizard with automatic UI selection:

gitlab-mcp-server --setup

Auto mode tries the richest available interface first: Web UI, then TUI, then plain CLI.

Choose a UI mode

Use --setup-mode when you want a specific interface:

gitlab-mcp-server --setup --setup-mode web

The Web wizard starts a temporary local server on 127.0.0.1, opens your browser, and waits until configuration is complete. It is the best choice for first-time setup because advanced options include inline help tooltips.

gitlab-mcp-server --setup --setup-mode tui

The TUI wizard runs in your terminal with keyboard navigation. Use it when you are working in an interactive shell and prefer not to open a browser.

gitlab-mcp-server --setup --setup-mode cli

The CLI wizard asks one question at a time. Use it for headless terminals, SSH sessions, or environments where browser and TUI rendering are unavailable.

What the wizard does

Selects the install path for the gitlab-mcp-server binary.
Collects your GitLab URL and Personal Access Token.
Loads any existing wizard configuration so you can keep or change previous values.
Lets you choose supported MCP clients to configure.
Writes the shared stdio environment file and selected client configuration files.

Files written

The wizard keeps secrets out of client JSON files.

| File | Purpose | | -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ~/.gitlab-mcp-server.env | Stores GITLAB_URL, GITLAB_TOKEN, TLS, catalog, safety, upload, rate-limit, auto-update, and logging options. On Unix, it is written with 0600 permissions. | | Client configuration files | Store the MCP server entry for each selected client. Where supported, they reference the env file instead of embedding secrets. |

VS Code gets an envFile reference to ~/.gitlab-mcp-server.env. JetBrains IDEs are display-only in the wizard: it prints the JSON snippet for you to paste into the IDE.

Existing configuration

When ~/.gitlab-mcp-server.env already exists, the wizard loads it before showing the form or prompts. Existing values are preselected for GitLab URL, token, catalog mode, safety flags, auto-update, rate limits, log level, and other advanced options.

Leave the token field empty to keep the existing token. Enter a new token only when you want to rotate it.

Supported clients

The wizard can configure these stdio clients:

| Client | Behavior | | ------------------------ | ---------------------------------------------------------------------------- | | VS Code (GitHub Copilot) | Writes an MCP server entry and references the env file. Selected by default. | | Claude Desktop | Writes the desktop MCP configuration file. | | Claude Code (CLI) | Writes the Claude Code MCP configuration file. | | Cursor | Writes Cursor’s MCP configuration file. | | Windsurf (Codeium) | Writes Windsurf’s MCP configuration file. | | JetBrains IDEs | Prints JSON for manual copy. | | Copilot CLI | Writes the Copilot CLI MCP configuration file. Selected by default. | | OpenCode | Writes OpenCode’s MCP configuration file. | | Crush (Charm) | Writes Crush’s MCP configuration file. | | Zed | Writes Zed’s MCP configuration file. |

Advanced options

Advanced options map to stdio environment variables written to ~/.gitlab-mcp-server.env.

| Wizard option | Environment variable | Description | | -------------------------- | ------------------------ | -------------------------------------------------------------- | | Skip TLS verification | GITLAB_SKIP_TLS_VERIFY | Allows self-signed or private CA GitLab certificates. | | Tool surface | TOOL_SURFACE | Chooses meta, individual, or dynamic. | | Capability surface | CAPABILITY_SURFACE | Chooses full resources/prompts or minimal startup context. | | Meta parameter schema | META_PARAM_SCHEMA | Controls meta-tool input schema detail. | | Enterprise/Premium catalog | GITLAB_ENTERPRISE | Enables Premium/Ultimate tools in stdio mode. | | Read-only mode | GITLAB_READ_ONLY | Registers only non-mutating tools. | | Safe mode previews | GITLAB_SAFE_MODE | Returns previews for mutating calls instead of executing them. | | Embedded resources | EMBEDDED_RESOURCES | Adds canonical MCP resource links to get-style results. | | Ignore PAT scopes | GITLAB_IGNORE_SCOPES | Skips token scope detection and registers all tools. | | Excluded tools | EXCLUDE_TOOLS | Omits comma-separated tool names from registration. | | Upload max file size | UPLOAD_MAX_FILE_SIZE | Sets the maximum accepted upload/file size. | | Auto-update mode | AUTO_UPDATE | Applies, checks, or disables background updates. | | Auto-update repository | AUTO_UPDATE_REPO | Selects the GitHub release repository used for update checks. | | Auto-update timeout | AUTO_UPDATE_TIMEOUT | Limits time spent on startup/background update checks. | | Rate limit RPS | RATE_LIMIT_RPS | Sets the stdio tool-call rate limit; 0 disables it. | | Rate limit burst | RATE_LIMIT_BURST | Sets token-bucket burst size when rate limiting is enabled. | | YOLO mode | YOLO_MODE | Skips selected local safety confirmations. Use carefully. | | Log level | LOG_LEVEL | Sets debug, info, warn, or error logging. |

HTTP-only server options, such as OAuth mode, session timeout, max HTTP clients, and HTTP auto-update interval, do not appear in the wizard because those belong to the long-running HTTP server process.

Reconfigure later

Run the wizard again at any time:

gitlab-mcp-server --setup

The wizard loads the existing env file first, so you can change only the values you need.

Next steps

See Configuration for the full environment variable reference.
See Dynamic Toolset for low-token tool catalog guidance.
See HTTP Server Mode for shared or remote deployments.