@wanadev/mcp-gitlab

A Model Context Protocol (MCP) server that gives project managers and developers full control over GitLab epics, issues, milestones, iterations, merge requests, code review, pipelines, branches, repository content, labels, boards, members, and governance from Claude Desktop, Claude Code, or any MCP-compatible client.

Why this MCP server?

Existing tools like glab are developer-oriented and CLI-only. @wanadev/mcp-gitlab covers both lenses -- planning and code -- through a conversational interface:

• Epics, milestones & iterations -- create, update, close, reopen, and link issues to epics. Track sprints with iterations (CRUD). Set health status (on track / needs attention / at risk) and view progress via Work Items API. Attach issues under epics via the modern hierarchy widget.

• Full MR lifecycle -- create, update, merge, rebase, approve, diff, and comment on merge requests.

• Code review -- create line-positioned discussions on MR diffs and resolve them.

• CI/CD -- list and inspect pipelines, fetch job logs, retry or cancel runs.

• Repository content -- list/create branches, browse the tree, read files, list commits, and write files (create / update / delete / atomic multi-file commits).

• Search -- full-text search across issues, MRs, and code blobs at project or group scope.

• Members management -- add, update, and remove group/project members with access levels.

• Governance -- list and manage protected branches and MR approval rules.

• Uploads -- upload images/binaries to embed in issues, MRs, and epics.

• Labels & users -- CRUD on labels, search users to assign work.

• Cross-group visibility -- query multiple GitLab groups in the same conversation (no hardcoded group ID).

• Time tracking -- see estimated vs. spent time on issues at a glance.

• Comments (notes) -- read, add, edit, and delete notes on issues, epics, and MRs.

• Dry-run by default -- every write operation previews what it will do before touching GitLab.

Quick setup

Prerequisites

• Node.js >= 20

• A GitLab Personal Access Token (PAT) with the api scope (or read_api for read-only access)

• GitLab Premium/Ultimate for epics and iterations (issues, milestones, MRs, labels, and boards work with all editions)

1. Generate a GitLab token

1. Go to GitLab > Settings > Access Tokens

2. Create a token with the api scope

3. Copy the token

2. Install

Claude Code (plugin)

/plugin marketplace add wanadev/gitlab-mcp
/plugin install wanadev-gitlab@wanadev-gitlab

Set GITLAB_TOKEN in your environment (.bashrc, .zshrc, or system variable). The plugin will guide you on first launch if it's missing.

Claude Desktop (manual config)

Add the following to your claude_desktop_config.json:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@wanadev/mcp-gitlab"],
      "env": {
        "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_BASE_URL": "https://gitlab.com",
        "GITLAB_READ_ONLY": "false"
      }
    }
  }
}

3. Restart and test

The MCP server will be available immediately. Test with: "List my GitLab groups"

Environment variables

Note: There is no GITLAB_GROUP_ID environment variable. Every group-scoped tool takes a group_id parameter. Use list_groups to discover accessible groups -- the LLM does this automatically.

Dry-run safety

All write tools (create_*, update_*, close_*, set_*, add_*) include a dry_run parameter that defaults to true.

This prevents accidental changes: the LLM always shows what it intends to do first and only proceeds after your approval.

All 100 tools

Epics (12 tools -- requires GitLab Premium/Ultimate)

Work Items (9 tools -- requires GitLab Premium/Ultimate)

Issues (11 tools)

Milestones (10 tools)

Merge Requests (18 tools)

CI/CD (5 tools)

Branches & Repository (12 tools)

Iterations (3 tools -- requires GitLab Premium/Ultimate)

Utilities (20 tools)

A gitlab_setup helper tool is also registered automatically when GITLAB_TOKEN is missing or GITLAB_BASE_URL is invalid — it guides the user through configuration and is not counted in the 100 above.

Example prompts

• "List my GitLab groups"

• "Show open epics in group 42"

• "What's the health status and progress of epic #5?"

• "Set epic #12 health status to 'needs attention'"

• "Link epic #3 as blocking issue #45"

• "List issues labeled bug in the wanadev group"

• "Create an epic called 'Homepage Redesign' in group 42 with a deadline of April 30"

• "Which issues are linked to epic #5 in the wanadev group?"

• "Close issue #15 in project 789"

• "Who are the members of the wanadev group?"

• "Show me all open merge requests in group 42"

• "How much time has been spent on issue #23 in project 456?"

• "Add a comment on epic #3 in group 42: Specs validated, ready for dev"

• "What milestones are coming up in the wanadev group?"

• "List the boards for group 42"

• "Open an MR from feat/new-login to main in project 789, then request review from @alice"

• "Show me the diff of MR !42 and summarize the changes"

• "List the last 5 failed pipelines on main in project 789 and fetch the log of the failing job"

• "Retry pipeline 12345 in project 789"

• "Create a release/2026.05 branch from main in project 789"

• "Read the contents of package.json on branch main in project 789"

• "Find a user named 'Jean Dupont' and assign them issue #15"

• "Rebase MR !42 on top of main"

• "Comment on line 73 of src/auth.ts in MR !42 — this should be wrapped in a try/catch"

• "Search the wanadev group for issues mentioning 'CVE-2024'"

• "Show me where processPayment is used across project 789"

• "Add @alice as Developer (level 30) to the kp1/api project"

• "Protect main on project 789 — only maintainers can merge, no direct pushes"

• "Set up a 2-approval rule named 'security' on project 789, applies to all protected branches"

• "Attach issues #12, #14, and #18 as children of epic #5 in the wanadev group"

• "Upload screenshot.png to project 789 and embed it in issue #15"

Use cases for project managers

Sprint planning

"List the active milestones in the wanadev group. For each one, show me the open issues and how many are unassigned."

Claude calls list_milestones → list_issues per milestone → summarizes the gaps. You see at a glance what's on track and what needs attention.

Daily standup prep

"Show me all open MRs in the [project] group that have been waiting for review for more than 3 days. Also list any issues that were closed yesterday."

Claude calls list_merge_requests (state: opened) → list_issues (state: closed, sort: updated_at) → gives you a ready-made standup brief.

Epic progress review

"Give me a status report on epic #12 in group wanadev: how many issues are done vs. open, what's the total time spent, and list the latest comments."

Claude chains get_epic → list_epic_issues → reads time_stats from each issue → list_epic_notes → returns a structured progress report.

Cross-group dashboard

"Compare the open issue count across my three groups: wanadev, [project], and infra. Which group has the most overdue issues?"

Claude calls list_groups → list_issues for each group with due date filtering → builds a comparison table.

Quick issue triage

"In the [project] group, find all issues labeled 'urgent' with no assignee. Assign them to @jean and add a comment saying 'Triaged in weekly review'."

Claude calls list_issues (labels: urgent) → for each unassigned issue, dry-runs update_issue (assignee) + add_issue_note → shows you the plan → you confirm → done.

Milestone closure

"Close milestone 'Sprint 14' in group wanadev. Before that, show me any issues still open in it."

Claude calls list_issues (milestone: Sprint 14, state: opened) → warns you about remaining items → dry-runs close_milestone → you confirm.

Development

git clone https://github.com/wanadev/gitlab-mcp.git
cd gitlab-mcp
npm install
npm run build       # Build ESM (tsc)
npm run typecheck   # TypeScript type checking
npm run dev         # Build in watch mode

Notes

• issue_id vs issue_iid -- add_issue_to_epic requires the global issue ID (not the #iid displayed in the project). Both list_issues and list_epic_issues return both values.

• Read-only mode -- With GITLAB_READ_ONLY=true, any create/update/close attempt returns a clear error.

• 403 on epics -- Epic endpoints require a GitLab Premium or Ultimate license.

• Multi-group workflow -- You can work across several groups in a single conversation. The LLM will call list_groups to discover them, then pass the right group_id to each tool.

• GitLab CE / Free support -- The server introspects your GitLab instance at startup and detects whether Issue.weight / Issue.epic are available (Premium/Ultimate-only fields). On Free/CE, those fields are silently omitted from queries and mutations, so all issue tools work — only epic-specific features remain Premium. The detected tier is logged at startup: [..., Premium/Ultimate] or [..., Free/CE].