GitLab MCP Quick Start Guide

Get GitLab MCP Server running with your AI agent in under a minute.

Recommended

Use the Setup Wizard for guided configuration:

npx @structured-world/gitlab-mcp setup

1. Get a GitLab Token

Create a Personal Access Token with api and read_user scopes.

First time?

See the step-by-step authentication guide for detailed instructions on token creation and scope selection.

2. Configure Your MCP Client

The example below is for Claude Desktop and Cursor. VS Code workspace configuration uses servers instead of mcpServers; follow the VS Code guide. For Codex, use the plugin or manual setup guide. Other clients have their own configuration formats.

Add the following to a compatible client's configuration:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

That's it. The server starts with all default tools enabled.

Optional Configuration

Variable	Purpose	Default
GITLAB_PROJECT_ID	Default project context	—
GITLAB_READ_ONLY_MODE	Restrict to read-only tools	false
GITLAB_API_HEADERS_TIMEOUT_MS	Response headers timeout in ms	10000
GITLAB_API_BODY_TIMEOUT_MS	Response body timeout in ms	30000
GITLAB_API_CONNECT_TIMEOUT_MS	TCP connect timeout in ms	2000

Feature Flags

Enable or disable tool groups:

Flag	Default	Tools
USE_LABELS	true	Label management
USE_MRS	true	Merge request operations
USE_FILES	true	File browsing and management
USE_VARIABLES	true	CI/CD variables
USE_WORKITEMS	true	Issues, epics, tasks (GraphQL)
USE_WEBHOOKS	true	Webhook management
USE_SNIPPETS	true	Code snippets
USE_INTEGRATIONS	true	50+ project integrations
USE_GITLAB_WIKI	true	Wiki pages
USE_MILESTONE	true	Milestone tracking
USE_PIPELINE	true	Pipeline and CI/CD jobs
USE_RELEASES	true	Release management
USE_REFS	true	Branch and tag management
USE_MEMBERS	true	Team member management
USE_SEARCH	true	Cross-project search
USE_ITERATIONS	true	Iteration planning (sprints)
USE_CI_TOKENS	true	CI access credentials: job token scope and deploy keys
USE_ENVIRONMENTS	true	Environments and deployments
USE_RUNNERS	true	CI runner management
USE_REGISTRY	true	Container registry repositories and tags
USE_ACCESS_TOKENS	true	Project/group/personal access token management
USE_AUDIT_EVENTS	true	Audit events (Premium+)
USE_VULNERABILITIES	true	Vulnerability management (Ultimate)

Next Steps

• Setup Wizard — interactive guided setup
• Supported Clients — per-client configuration guides
• Deployment Options — local vs Docker vs server
• All environment variables
• CLI Reference — all available commands
• OAuth for teams