GitLab MCP Setup Wizard

Interactive setup wizard that guides you through configuring GitLab MCP. Detects your environment, walks through GitLab authentication, and installs configuration to your MCP clients or Docker.

Usage

gitlab-mcp setup [--mode=<mode>]

Options

Flag	Description	Values
--mode	Skip mode selection	local, server, configure-existing

Modes

Local (stdio)

Configures GitLab MCP for local AI IDE clients. The wizard:

1. Prompts for GitLab instance URL
2. Guides through token creation/entry
3. Tests the connection
4. Configures tool selection (preset/manual/advanced)
   • Advanced mode includes: feature flags, read-only mode, cross-reference hints (GITLAB_CROSS_REFS), scope restrictions, and log level
5. Detects and installs to selected MCP clients

gitlab-mcp setup --mode=local
# or use the alias:
gitlab-mcp init

Server (HTTP/SSE)

Sets up GitLab MCP as a Docker-based HTTP server. The wizard:

1. Verifies Docker and Docker Compose
2. Selects deployment type (standalone, external-db, compose-bundle)
3. Configures port and optional OAuth
4. Generates docker-compose.yml and .env
5. Optionally starts the container

gitlab-mcp setup --mode=server
# or use the alias:
gitlab-mcp docker init

Configure Existing

Modifies an existing GitLab MCP installation:

1. Detects configured clients and running containers
2. Lets you choose what to modify
3. Updates token, URL, tool groups, or preset

gitlab-mcp setup --mode=configure-existing

Discovery Phase

Before mode selection, the wizard runs automatic discovery:

Detection	Method
Claude Desktop	macOS app bundle (com.anthropic.claudefordesktop)
Claude Code	CLI command (claude)
Cursor	Config directory (~/.cursor/)
VS Code	Config directory (.vscode/)
Windsurf	Config directory (~/.codeium/windsurf/)
Cline	VS Code extension storage
Roo Code	Config directory (~/.roo/)
Docker	docker and docker compose commands

Examples

# Full interactive wizard
npx @structured-world/gitlab-mcp setup

# Direct to local setup
npx @structured-world/gitlab-mcp setup --mode=local

# Direct to server setup
npx @structured-world/gitlab-mcp setup --mode=server

# Modify existing configuration
npx @structured-world/gitlab-mcp setup --mode=configure-existing

Exit Codes

Code	Meaning
0	Setup completed successfully
1	Setup failed or was cancelled

See Also

• Setup Wizard walkthrough
• gitlab-mcp init — alias for local setup
• gitlab-mcp install — client installation only
• gitlab-mcp docker — Docker management