GitLab is more than a code platform — it's a complete DevSecOps lifecycle tool with built-in CI/CD, container registry, security scanning, and issue tracking. GitLab's official MCP server connects all of that to your AI assistant, making repository management, code review, and pipeline debugging significantly faster.
This guide covers everything you need to set up and use the GitLab MCP server with Claude, Cursor, and VS Code.
What the GitLab MCP Server Can Do
GitLab's MCP server is one of the most feature-rich in the ecosystem, covering the full GitLab project lifecycle:
- Repository access: Browse files, read code, explore commit history
- Merge requests: List, search, read diffs, view review comments, check approval status
- Issues: Search, create, update, and triage issues and epics
- CI/CD pipelines: View pipeline runs, job logs, and deployment environments
- Wikis: Read and search project wiki pages
- Users and groups: Access team member info and namespace structures
Prerequisites
- GitLab account — GitLab.com or a self-hosted instance
- Personal Access Token (PAT) — with
read_apiscope at minimum; addwrite_repositoryif you want to create issues from your AI assistant - Node.js 18+ installed on your machine
Creating a GitLab PAT
- Go to GitLab → User Settings → Access Tokens
- Create a token with name:
mcp-server - Scopes:
read_api, optionallywrite_repository - Set an expiration date (recommended: 90 days)
- Copy and save the token — you won't see it again
Installation
npx @gitlab-org/gitlab-mcp-server --token YOUR_GITLAB_TOKENFor self-hosted GitLab instances:
npx @gitlab-org/gitlab-mcp-server --token YOUR_TOKEN --url https://gitlab.yourcompany.comConfiguration: Claude Desktop
Add to your ~/.config/claude/claude_desktop_config.json:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["@gitlab-org/gitlab-mcp-server"],
"env": {
"GITLAB_TOKEN": "your_personal_access_token",
"GITLAB_URL": "https://gitlab.com"
}
}
}
}Restart Claude Desktop after saving. You'll see the GitLab tools appear in Claude's tool list.
Configuration: Cursor
Open Cursor Settings → MCP → Add Server:
- Name: GitLab
- Command:
npx @gitlab-org/gitlab-mcp-server - Environment:
GITLAB_TOKEN=your_token
Configuration: VS Code
Add to your .vscode/mcp.json (workspace-level) or user settings:
{
"servers": {
"gitlab": {
"type": "stdio",
"command": "npx",
"args": ["@gitlab-org/gitlab-mcp-server"],
"env": {
"GITLAB_TOKEN": "your_token"
}
}
}
}Best Use Cases
Merge Request Reviews
"Show me all open MRs assigned to me in the backend group, summarize the changes in each, and flag any that haven't had activity in 7+ days."
Issue Triage
"Find all issues labeled 'bug' created in the last 14 days with no assignee. Rank them by comment activity and suggest which 3 should be prioritized for this sprint."
Pipeline Debugging
"The deploy-production pipeline failed 3 times in the last 24 hours. Show me the job logs for each failure and identify the common failure point."
Code Archaeology
"Find all commits in the auth module from the last 90 days that touched the token validation logic. Summarize what changed and why based on commit messages and MR descriptions."
Documentation Gaps
"Read the project wiki and identify which API endpoints documented in the code have no corresponding wiki page."
GitLab MCP vs. GitHub MCP
If your team uses both platforms (common in enterprise environments), here's the key difference:
- GitLab MCP is stronger on CI/CD (native pipeline integration), security scanning results, and issue/epic hierarchy
- GitHub MCP is stronger on community integrations, GitHub Actions ecosystem, and public repository search
You can run both simultaneously — each serves different project contexts without conflict.
Pairing GitLab with Other MCP Servers
The most productive combinations:
- GitLab + Docker MCP — manage the container registry and deployed images alongside code
- GitLab + Kubernetes MCP — correlate GitLab pipeline deployments with cluster state
- GitLab + CircleCI/Jenkins — if you use external CI alongside GitLab for specific pipelines
- GitLab + Filesystem — local code access + remote repository state for full context
Troubleshooting
Authentication fails: Verify your PAT hasn't expired and has read_api scope. Self-hosted instances may need GITLAB_URL set explicitly.
Rate limiting: GitLab's API rate limits are 2,000 requests/hour for authenticated users. If you're hitting limits, add --rate-limit-delay 100 to introduce a 100ms delay between calls.
Self-hosted SSL: If you get SSL certificate errors on self-managed GitLab, set NODE_TLS_REJECT_UNAUTHORIZED=0 in the env config (only for trusted internal networks).
MR diffs not loading: Large MRs (>1,000 lines changed) may exceed context limits. Use the --max-diff-lines 500 flag to truncate large diffs automatically.
Related guides: