GitLab MCP Server Cursor IDE Setup 2026
Set up GitLab MCP server in Cursor IDE: Personal Access Token config, mcp.json block, and self-hosted setup. Enable AI merge request & pipeline management.
GitLab MCP Server Cursor IDE Setup 2026
How do you set up the GitLab MCP server in Cursor? Generate a Personal Access Token with api scope, add a gitlab block to ~/.cursor/mcp.json with that token and your GitLab API URL, then restart Cursor. Once connected, your AI can read merge requests, check CI/CD pipeline status, and manage issues without switching to a browser tab. This works the same way on GitLab.com and on a self-hosted CE/EE instance — only the API URL changes.
This guide covers the full 2026 setup, including self-hosted configuration and the errors people actually hit.
Quick Reference
| | |
|---|---|
| Auth method | Personal Access Token (api scope required for writes) |
| Config key | GITLAB_PERSONAL_ACCESS_TOKEN |
| API URL (SaaS) | https://gitlab.com/api/v4 |
| API URL (self-hosted) | https://gitlab.yourcompany.com/api/v4 |
| Package | @modelcontextprotocol/server-gitlab (or gitlab-mcp-server) |
| Setup time | ~10 minutes |
| Works on | GitLab.com, self-hosted CE/EE |
What the GitLab MCP Server Enables
Once connected, Cursor can:
Prerequisites
Step 1: Create a GitLab Personal Access Token
1. Log into GitLab → click your avatar → Preferences
2. Go to Access Tokens in the left sidebar
3. Click Add new token
4. Name it cursor-mcp-2026
5. Set an expiration date (or leave blank for no expiry)
6. Select these scopes:
api — full API access (required for MR creation and pipeline triggers)read_repository — read repo contentswrite_repository — create branches and push7. Click Create personal access token
8. Copy the token immediately — it will not be shown again
Step 2: Install the GitLab MCP Server
npm install -g @modelcontextprotocol/server-gitlab
Or use the community package:
npm install -g gitlab-mcp-server
Verify the installation:
gitlab-mcp-server --version
Step 3: Configure Cursor IDE
Open Cursor → Settings → MCP and add the GitLab server config:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-gitlab"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com/api/v4"
}
}
}
}
For self-hosted GitLab, change the API URL:
"GITLAB_API_URL": "https://gitlab.yourcompany.com/api/v4"
Restart Cursor to load the configuration.
Step 4: Test the Connection
In Cursor chat, try:
List my GitLab projects
Or:
Show me the open merge requests in the backend-api project
A successful response with real data confirms the connection is working.
Step 5: Real-World Usage Patterns
Code review assistance
Read merge request !47 in the payments-service project. Summarize the changes and flag any potential issues before I approve it.
Pre-push pipeline check
What's the status of the last CI/CD pipeline on the main branch of payments-service? Did all jobs pass?
Automated MR creation
I just finished implementing the Stripe webhook handler. Create a merge request from feature/stripe-webhooks to main with a description summarizing the changes.
Branch management
Create a new branch called feature/PROJ-892-payment-refactor from main in the backend-api project.
Issue-driven development
Find issue #234 in the frontend project, read the acceptance criteria, then implement what's described in the current working directory.
Pipeline job debugging
The deploy-staging job failed in the last pipeline on feature/new-auth. Fetch the job log and tell me what went wrong.
Self-Hosted GitLab Configuration
For GitLab Self-Managed (CE or EE), the setup is the same but with your instance URL:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-gitlab"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.yourcompany.com/api/v4",
"GITLAB_DEFAULT_NAMESPACE": "your-group-or-username"
}
}
}
}
If your self-hosted instance uses a self-signed certificate, you may need:
"NODE_TLS_REJECT_UNAUTHORIZED": "0"
(Only use this in a trusted corporate environment — it disables TLS verification.)
GitLab MCP Server Setup Time: What to Actually Expect in 2026
Generating the token in Step 1 takes about two minutes. The mcp.json block in Step 3 is four lines. Most of the 10-minute estimate elsewhere on this page is the restart-and-verify loop, not the config itself — if your first test prompt in Step 4 comes back empty rather than erroring, that's almost always a token scope problem (see Troubleshooting), not a sign the setup is more involved than it looks.
One thing worth deciding upfront rather than after you hit it: whether this token lives on your personal GitLab account or a dedicated service account. A personal token ties the AI's GitLab access to everything you can see; a service account scoped to specific projects is more setup work now but a cleaner blast radius later.
GitLab vs GitHub MCP: Which Should You Use?
If your team is split between GitLab and GitHub, you can run both MCP servers simultaneously:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-gitlab"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxx"
}
},
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": {
"GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxx"
}
}
}
}
Cursor will have access to both simultaneously. Specify the platform in your prompts: "in GitLab, create a merge request..." vs "on GitHub, open a pull request..."
Troubleshooting
"403 Forbidden" when creating MRs
You need the api scope on your token — read_repository alone is not sufficient for write operations.
"Project not found" error
Use the full project path: group/subgroup/project-name, not just the project name. GitLab requires the namespace path for unambiguous project references.
Self-hosted SSL errors
If you get certificate errors on a self-hosted instance, ensure your system trusts the certificate authority. Running curl https://gitlab.yourcompany.com/api/v4/version in terminal will show you the same error Cursor sees.
Rate limiting
GitLab API rate limits are typically 2,000 requests/minute for authenticated users. For bulk operations, add natural language pacing: "check the 5 most recent MRs" rather than "check all open MRs."
Token works in curl but Cursor still shows "unauthorized"
Check for a stray newline or space pasted alongside the token in mcp.json — it's valid JSON either way, so the file won't error, but GitLab will reject the malformed token string. Retype the value instead of copy-pasting if this happens twice.
MR created but pipeline never triggers
Some GitLab CI configurations only run pipelines on specific branch patterns or via merge request events, not on every push. Confirm your .gitlab-ci.yml rules actually match the branch the MCP server created — this is a CI config issue, not an MCP one.
When Not to Use This
If your .gitlab-ci.yml deploys automatically on merge, be deliberate about letting an AI-driven workflow create and merge MRs unattended — a model that's confidently wrong about "this is safe to merge" combined with an auto-deploying pipeline is a bad combination. Keep merge approval manual even after you automate the MR creation and review-summary steps.
Frequently Asked Questions
Q: Does this work with GitLab.com, or only self-hosted instances?
A: Both. Point GITLAB_API_URL at https://gitlab.com/api/v4 for GitLab.com, or your instance's API path for self-hosted GitLab CE/EE — the token scopes and MCP config are otherwise identical.
Q: My AI can read merge requests but can't create or approve them — why?
A: Check the scope on your Personal Access Token, not the MCP config. read_repository covers read-only operations; creating, approving, or merging MRs needs the broader api scope.
Q: Can I restrict which projects the AI can see?
A: Not at the MCP config level in most setups — the token's own permissions define scope. If you need to limit blast radius, create a token under a service account with membership in only the specific projects you want exposed, rather than your personal account's full project list.
Q: How is this different from just using GitLab's web UI or CLI (glab)?
A: The MCP server lets the AI chain GitLab context with your local code in one conversation — for example, reading a merge request's diff and then checking it against your working tree, without you copying anything between windows. glab is still the better tool for scripting or one-off manual commands outside an AI session.
Q: Do GitLab MCP and GitHub MCP conflict if I run both at once?
A: No — they're independent config entries in mcp.json, and you tell Cursor which platform you mean in your prompt ("in GitLab..." vs "on GitHub..."). This is a common setup for teams migrating between the two or maintaining mirrors on both.
Q: What's the complete GitLab MCP server Cursor IDE setup for 2026, in order?
A: Generate a Personal Access Token with api scope (Step 1), install the server package (Step 2), add the gitlab block from Step 3 to mcp.json with the token and API URL, then restart Cursor and confirm with a read-only prompt like listing your projects. Self-hosted instances only change the GITLAB_API_URL value, nothing else in the schema.
Q: Does the setup change for a self-hosted GitLab instance versus GitLab.com?
A: Only one field changes: point GITLAB_API_URL at your instance's /api/v4 path instead of gitlab.com/api/v4. The token scopes, the rest of the mcp.json block, and the Cursor-side steps are identical either way.
Q: What's the exact gitlab mcp server cursor ide setup 2026 process, step by step?
A: Create a Personal Access Token with api scope (Step 1), install @modelcontextprotocol/server-gitlab or let npx fetch it on first run (Step 2), add the gitlab block to mcp.json with the token and GITLAB_API_URL (Step 3), restart Cursor, then confirm with a read-only prompt like "list my GitLab projects" (Step 4). Self-hosted instances change only the API URL — nothing else in the config differs.
Q: Can I use the GitLab MCP server alongside a CI/CD tool like CircleCI in the same Cursor session?
A: Yes — they're independent mcpServers entries. A common pairing is asking Cursor to check a merge request's diff via the GitLab connection, then check the corresponding pipeline status via a CircleCI MCP connection if your team runs CircleCI instead of GitLab's built-in CI/CD.
Summary
The GitLab MCP server is one of the most practically useful integrations for teams using GitLab as their primary DevOps platform. The ability to create MRs, check pipeline status, and read issue context from within Cursor removes significant context-switching overhead from daily development workflow.
Setup takes about 10 minutes. The key requirement is a Personal Access Token with api scope. Plenty of teams run GitLab for code alongside Jira for tickets and Confluence for docs — none of these MCP connections depend on each other, so mixing platforms across your Atlassian and GitLab tools isn't a special case, just three independent mcpServers entries. See our guides for Jira MCP, Confluence MCP, Bitbucket MCP, or the combined Atlassian MCP bundle if you want Jira, Confluence, and Bitbucket behind one connection instead.
Frequently Asked Questions (continued)
Q: My team tracks work in Jira but keeps code in GitLab instead of Bitbucket — does the MCP setup support that combination?
A: Yes. Nothing about the GitLab MCP server or the Jira MCP server assumes the other Atlassian products are in use — GitLab and Jira aren't the same vendor, and each connection is configured independently in mcp.json. Run both, and prompts like "pull the requirements from PROJ-456, then create a GitLab merge request implementing it" work across the two servers in one request, the same way the Bitbucket+Jira combination does for Atlassian-only teams.
Related Guides
---
Related guides
- Intercom MCP Server Cursor IDE Setup (2026): OAuth or Bearer Token via mcp-remote
- Jira MCP Server Cursor IDE Setup (2025-2026)
- Kubernetes MCP Server Setup for Cursor IDE (2026): Query Pods, Logs & Deployments from Chat
- LaunchDarkly MCP Server Cursor IDE Setup (2026): Feature Flags & Observability from Chat