gitlab-mcp setup

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