GitLab plugin for Cursor

Connect Cursor to your GitLab instance with the GitLab MCP server. Plan, track, and manage issues, merge requests, and pipelines — all from within your editor.

Note: This repository is mirrored on GitHub from GitLab. Please submit all merge requests and issues on GitLab. Pull requests and issues on GitHub will not be processed.

Requirements

• A GitLab.com account or a GitLab Self-Managed instance (18.3+).
• Available on all tiers, including Free, from GitLab 19.2, when the MCP server moved from Premium to Free. On earlier versions it requires Premium or Ultimate. The server is currently Beta.
• MCP server access allowed: on GitLab.com for the top-level group, and on GitLab Self-Managed or GitLab Dedicated for the instance.
• For toolset selection, GitLab 19.5 or later. This plugin sends the X-Gitlab-Enabled-Mcp-Server-Toolsets header. Earlier versions ignore it and serve the default toolsets.

Setup

The plugin points at gitlab.com. If you use a self-managed instance, read Self-Managed instances before you authorize, because approving the gitlab.com prompt is not what you want.

1. Install the GitLab plugin from the Cursor Marketplace.
2. Open Settings > Cursor Settings > Tools & MCP and verify that a GitLab MCP server appears. The plugin supplies its own configuration, so there is nothing to write by hand.
3. Wait for your browser to open the OAuth authorization page. If it does not, select Connect on the GitLab server, type mcp_auth in the Cursor chat, or restart Cursor.
4. Review and approve the authorization request.

"Unverified Dynamic Application" warning: During OAuth authorization, you may see a warning that Cursor is an unverified application. This is expected — Cursor uses OAuth Dynamic Client Registration, and GitLab flags all dynamically registered apps as unverified by design. The connection is still secure. Cursor is working with GitLab's Technology Partner team to get their OAuth application pre-registered and verified, which will remove this warning for all users.

Enterprise workaround: GitLab admins can eliminate the warning for their instance by pre-registering Cursor as a trusted application. Go to Admin Area → Applications → New Application, register Cursor, and enable Trusted. This removes the warning and skips the consent screen for all users on that instance.

Self-Managed instances

The plugin ships a .mcp.json that points at gitlab.com, and Cursor installs it into its own plugin cache rather than into your project. No setting changes that URL or turns the bundled server off, so pointing the plugin at your instance means editing the cached file. Tracked in issue #2.

1. Find the plugin's .mcp.json under ~/.cursor/plugins/cache/.
2. Replace the host with your instance, keeping the /api/v4/mcp path. The .mcp.json.self-managed.example file in this repository shows the shape to match.
3. Remove any GitLab server you configured yourself in ~/.cursor/mcp.json. Two servers named GitLab leave Cursor asking you to authorize gitlab.com even after your own one is connected.
4. Restart Cursor and authorize again. Your browser should now open your instance instead of gitlab.com.

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://gitlab.example.com/api/v4/mcp",
      "headers": {
        "X-Gitlab-Enabled-Mcp-Server-Toolsets": "all"
      }
    }
  }
}

A plugin update can overwrite the cached file and put gitlab.com back, so check this again after upgrading.

What's included

MCP server

The core of this plugin. The GitLab MCP server gives Cursor direct access to your GitLab data. Tools are grouped into toolsets, and the plugin's MCP configuration sends X-Gitlab-Enabled-Mcp-Server-Toolsets: all, so every toolset is enabled, including the three that are otherwise opt-in:

Toolset	Enabled by default	Covers
meta	Always	MCP server metadata
core	Yes	Projects, groups, users, search, and labels
merge_requests	Yes	Merge requests, diffs, notes, reviews, and approvals
work_items	Yes	Issues, epics, tasks, and their comments
repository	Yes	Branches, commits, files, tags, and releases
ci	Yes	Pipelines, jobs, job logs, and artifacts
duo_agent_platform	Opt-in	Starting and tracking Duo Agent Platform sessions
wikis	Opt-in	Wiki pages
code_security	Opt-in	Vulnerability triage and scan profiles

Enabling a toolset does not bypass the tier and edition checks on the tools inside it. code_security needs Ultimate, duo_agent_platform needs GitLab Duo on Premium or Ultimate, and semantic_search in core exists only in Enterprise Edition. On a plan or edition without them, the toolset lists no tools or the calls fail a license check.

To narrow the list, replace all with a comma-separated subset, for example core,merge_requests,code_security. Narrowing is worth doing if you run several MCP servers at once, because a large combined tool list makes it more likely the model picks the wrong tool. Toolset names are matched without regard to case, and an unrecognized name returns a 400 error.

For the current per-tool reference, see the MCP server tools documentation.

Rules

• gitlab-workflow — GitLab development conventions (conventional commits, issue references, small merge requests).

Skills

• gitlab-ci-author — Helps write, debug, and optimize .gitlab-ci.yml pipeline configuration.

Agents

• gitlab-assistant (GitLab Assistant) — AI agent with product management capabilities that helps with Agile planning, prioritization, delivery tracking, and stakeholder communication using the MCP server.

Commands

• create-issue — Create an issue with labels, milestone, and assignees.
• create-merge-request — Create a merge request from the current branch.
• review-merge-request — Review a merge request: summarize changes, check pipelines, and flag concerns.
• pipeline-status — Check pipeline health and drill into failed jobs.
• plan-sprint — Analyze open issues and suggest sprint scope and priorities.
• backlog-health — Assess the backlog for staleness, missing labels, and unassigned work.

Example prompts

Try these in Cursor chat. Prefix your prompt with /gitlab-assistant to route it to the GitLab agent:

Issues and planning

• "/gitlab-assistant Show me all open issues labeled bug in my-group/my-project"
• "/gitlab-assistant Create an issue for the API rate limiting feature with appropriate labels"
• "/gitlab-assistant What issues are assigned to me in this project?"
• "/gitlab-assistant Summarize the open issues in milestone 3.2"

Sprint and backlog

• "/gitlab-assistant Help me plan the next sprint for milestone 3.2 in my-group/my-project"
• "/gitlab-assistant Analyze the backlog health for my-group/my-project"
• "/gitlab-assistant Which open issues have no assignee or labels?"

Merge requests

• "/gitlab-assistant Create a merge request from my current branch to main"
• "/gitlab-assistant Review merge request !142 in my-group/my-project"
• "/gitlab-assistant What files changed in MR !89?"
• "/gitlab-assistant Show me the commits in merge request !56"

Pipelines and CI/CD

• "/gitlab-assistant What's the pipeline status for my-group/my-project?"
• "/gitlab-assistant Which jobs failed in the latest pipeline?"
• "/gitlab-assistant Retry the failed pipeline for this project"

Search and discovery

• "/gitlab-assistant Search for issues mentioning 'authentication timeout'"
• "/gitlab-assistant Find code related to user permissions in my-group/my-project"
• "/gitlab-assistant What labels are available in this project?"

Comments and collaboration

• "/gitlab-assistant Show me the comments on issue #42 in my-group/my-project"
• "/gitlab-assistant Add a comment to issue #42 summarizing the investigation"

GitLab Duo Agent Platform

This plugin gives you core GitLab workflows in Cursor. For AI-powered agents that can autonomously plan, analyze, create code, review merge requests, fix pipelines, and more, explore the GitLab Duo Agent Platform and the GitLab Agent Catalog.

The MCP server in this plugin works on every tier, but the agents and flows below need GitLab Premium or Ultimate with GitLab Duo and beta features enabled. Compare plans or start a free trial.

Foundational Agents

• Planner Agent — Full work item CRUD, epic/task hierarchy, dependency analysis, estimation, and planning workflows.
• Security Analyst Agent — Vulnerability triage, risk assessment, compliance reporting, and remediation planning.
• Data Analyst Agent — GLQL queries, volume analysis, team performance metrics, and trend visualization.

Foundational Flows

• Software Development Flow — AI-generated solutions across the software development lifecycle.
• Developer Flow — Convert issues into merge requests.
• Fix CI/CD Pipeline Flow — Diagnose and fix failing pipelines.
• Code Review Flow — Automate code review with AI-native analysis.
• Convert to GitLab CI/CD Flow — Migrate legacy CI/CD to GitLab.
• Agentic SAST Vulnerability Resolution — Auto-generate merge requests to fix SAST vulnerabilities.
• SAST False Positive Detection — Identify and filter false positives in SAST findings.

Extend further

• Custom agents — Build team-specific agents for your unique requirements.
• External agents — Connect third-party integrations (Claude Code, OpenAI Codex, Amazon Q, Gemini) to GitLab.

Links

• GitLab MCP server documentation
• MCP server tools reference
• GitLab Agent Catalog
• GitLab Duo Agent Platform

Contributing

See CONTRIBUTING.md for guidelines on how to contribute to this project.

License

MIT