Better GitLab MCP Server

Name: Better GitLab MCP Server
Author: zereight

LABSCO SUMMARY

A review that happens in the conversation rather than across twenty browser tabs.

What it takes off you is the click path through a merge request: the agent lists the changed files, pulls diffs for the ones that matter, leaves draft notes as it reads, publishes them in one pass with a reviewer state, and resolves the threads that got fixed. Issues, branches and CI lint sit behind the same token, and the permission mode decides how far it can go.

What it is

A wide GitLab server built around the review loop. Merge requests are the deepest part of it: diffs by file or by version, threads resolved, draft notes held back and published together, approvals and merges. It speaks stdio for local clients, SSE for older ones, and Streamable HTTP when you run it as a shared server.

What you get

Merge requests listed, created, updated, approved, merged, and read with deployment, commit and approval summaries
Diffs at every grain: the whole request, one file, one version, between two branches, and the changed-file list without any diff content — the two-step path for reviewing a large branch
Review threads: notes created, edited and resolved, and draft notes written as you go then published in one pass with a reviewer state
Issues created, updated, linked and deleted, with descriptions patched by search-replace or unified diff instead of a full rewrite
Emoji reactions on merge requests, issues and their notes
Repository work: files read and written, multi-file commits pushed, branches created, protected and unprotected, the default branch changed, and the tree listed
Commits listed and read with stats and diffs, blame narrowed to a line range, and commit statuses created
Projects, groups, namespaces, members and labels read and managed, plus to-do items and event history
CI configuration validated as content or as the project's own file, and the CI/CD catalog browsed
A write boundary you set once: GITLAB_PERMISSION_MODE=readonly for reads only, or modify to allow create and update while every delete tool stays out of the list
Toolsets kept out of the way until wanted — pipelines, milestones, wiki, releases, tags, workitems, webhooks, search, variables and more switch on through GITLAB_TOOLSETS, or discover_tools activates a category mid-session

Requirements

npx on your PATH and a GitLab personal access token in GITLAB_PERSONAL_ACCESS_TOKEN, scoped api or read_api. GITLAB_API_URL points at the instance and defaults to https://gitlab.com/api/v4, so a self-managed GitLab means setting it. Inside GitLab CI, GITLAB_JOB_TOKEN can stand in for the personal token; GITLAB_USE_OAUTH=true swaps the token for a browser sign-in instead.

Setup effort

One command plus a key — npm install -g @zereight/mcp-gitlab, then supply credentials

See installation options

USE CASES

01

Reviewing a merge request properly

List the changed files first, pull the diffs worth reading, write comments as drafts, then publish the whole set with a reviewer state attached.

list_merge_request_changed_filesget_merge_request_file_diffcreate_draft_notebulk_publish_draft_notes

02

Getting a merge request over the line

Who still has to approve, the approval itself, and the merge — with squash and source-branch removal — without opening the web UI.

get_merge_request_approval_stateapprove_merge_requestmerge_merge_request

03

Finding out when a line changed and why

Blame maps a range of lines to the commits that last touched them, and the commit and its diff explain what that change was for.

get_file_blameget_commitget_commit_diff

04

Triaging your own issue list

The issues assigned to you come back in one call, and small description edits go as a patch rather than a full rewrite.

my_issuesupdate_issue_description_patchcreate_issue_note

05

Letting an agent touch GitLab without letting it delete anything

Start the server with GITLAB_PERMISSION_MODE=modify — create and update stay available, every delete tool disappears from the list.

discover_toolshealth_check

06

Catching a broken pipeline config before pushing it

Validate the YAML you are about to commit, or the .gitlab-ci.yml already in the project, against the project's own CI settings.

validate_ci_lintvalidate_project_ci_lint

116 tools

Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.

`approve_merge_request`

Approve a merge request

BEFORE YOU INSTALL

What to know first

Tools you get

116 tools when we connected; the project documents 217. The rest sit in opt-in groups such as Pipelines, Wiki, Releases and Variables; enable them with GITLAB_TOOLSETS=all or a group list, or call discover_tools. GITLAB_PERMISSION_MODE=readonly hides every write tool.

Requires

npx on PATH
GITLAB_PERSONAL_ACCESS_TOKEN in your environment

INSTALLATION

Connect your client

Server setup

TERMINAL

npm install -g @zereight/mcp-gitlab

MCP Clients

VS Code

VS CODE · JSON

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "zereight.gitlab-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab@latest"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_PERMISSION_MODE": "full"
      }
    }
  }
}

Claude Code

CLAUDE CODE · TERMINAL

claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN> --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab

Cursor

CURSOR · JSON

{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}

Codex

CODEX · TERMINAL

codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN> --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab

GitHub Copilot CLI — Token argument

GITHUB COPILOT CLI — TOKEN ARGUMENT · JSON

{
  "mcpServers": {
    "gitlab": {
      "command": "zereight-mcp-gitlab",
      "args": [
        "--token=<YOUR_GITLAB_TOKEN>",
        "--api-url=https://gitlab.com/api/v4"
      ],
      "tools": [
        "*"
      ]
    }
  }
}

Any MCP client — Docker SSE

ANY MCP CLIENT — DOCKER SSE · TERMINAL

docker run -i --rm -e HOST=0.0.0.0 -e GITLAB_PERSONAL_ACCESS_TOKEN=<YOUR_GITLAB_PERSONAL_ACCESS_TOKEN> -e GITLAB_API_URL="https://gitlab.com/api/v4" -e GITLAB_PERMISSION_MODE=readonly -e GITLAB_TOOLSETS=wiki,milestones,pipelines -e SSE=true -e SSE_AUTH_TOKEN=<YOUR_SSE_AUTH_TOKEN> -p 3333:3002 zereight050/gitlab-mcp

ANY MCP CLIENT — DOCKER SSE · JSON

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse",
      "headers": {
        "Authorization": "Bearer <YOUR_SSE_AUTH_TOKEN>"
      }
    }
  }
}

Any MCP client — Docker HTTP

ANY MCP CLIENT — DOCKER HTTP · TERMINAL

docker run -i --rm -e HOST=0.0.0.0 -e REMOTE_AUTHORIZATION=true -e GITLAB_API_URL="https://gitlab.com/api/v4" -e GITLAB_PERMISSION_MODE=readonly -e GITLAB_TOOLSETS=wiki,milestones,pipelines -e STREAMABLE_HTTP=true -p 3333:3002 zereight050/gitlab-mcp

ANY MCP CLIENT — DOCKER HTTP · JSON

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_TOKEN>"
      }
    }
  }
}

Clients spell the "type" value differently: Claude Code and VS Code use "http", Cline uses "streamableHttp", and Roo Code uses "streamable-http". Claude Desktop does not accept a URL entry in its config file.

A review that happens in the conversation rather than across twenty browser tabs.

What it is

What you get

Requirements

Setup effort

Reviewing a merge request properly

Getting a merge request over the line

Finding out when a line changed and why

Triaging your own issue list

Letting an agent touch GitLab without letting it delete anything

Catching a broken pipeline config before pushing it

116 tools

approve_merge_request

bulk_publish_draft_notes

create_branch

create_commit_status

create_draft_note

create_group

create_issue

create_issue_emoji_reaction

create_issue_link

create_issue_note

create_issue_note_emoji_reaction

create_label

create_merge_request

create_merge_request_discussion_note

create_merge_request_emoji_reaction

create_merge_request_note

create_merge_request_note_emoji_reaction

create_merge_request_thread

create_note

create_or_update_file

create_repository

delete_branch

delete_draft_note

delete_issue

delete_issue_emoji_reaction

delete_issue_link

delete_issue_note_emoji_reaction

delete_label

delete_merge_request_discussion_note

delete_merge_request_emoji_reaction

delete_merge_request_note

delete_merge_request_note_emoji_reaction

discover_tools

download_attachment

fork_repository

get_branch

get_branch_diffs

get_ci_catalog_resource

get_commit

get_commit_diff

get_draft_note

get_file_blame

get_file_contents

get_issue

get_issue_link

get_label

get_merge_request

get_merge_request_approval_state

get_merge_request_conflicts

get_merge_request_diffs

get_merge_request_file_diff

get_merge_request_note

get_merge_request_notes

get_merge_request_version

get_namespace

get_project

get_project_events

get_protected_branch

get_repository_tree

get_user

get_users

health_check

list_branches

list_ci_catalog_resources

list_commit_statuses

list_commits

list_draft_notes

`approve_merge_request`

`bulk_publish_draft_notes`

`create_branch`

`create_commit_status`

`create_draft_note`

`create_group`

`create_issue`

`create_issue_emoji_reaction`

`create_issue_link`

`create_issue_note`

`create_issue_note_emoji_reaction`

`create_label`

`create_merge_request`

`create_merge_request_discussion_note`

`create_merge_request_emoji_reaction`

`create_merge_request_note`

`create_merge_request_note_emoji_reaction`

`create_merge_request_thread`

`create_note`

`create_or_update_file`

`create_repository`

`delete_branch`

`delete_draft_note`

`delete_issue`

`delete_issue_emoji_reaction`

`delete_issue_link`

`delete_issue_note_emoji_reaction`

`delete_label`

`delete_merge_request_discussion_note`

`delete_merge_request_emoji_reaction`

`delete_merge_request_note`

`delete_merge_request_note_emoji_reaction`

`discover_tools`

`download_attachment`

`fork_repository`

`get_branch`

`get_branch_diffs`

`get_ci_catalog_resource`

`get_commit`

`get_commit_diff`

`get_draft_note`

`get_file_blame`

`get_file_contents`

`get_issue`

`get_issue_link`

`get_label`

`get_merge_request`

`get_merge_request_approval_state`

`get_merge_request_conflicts`

`get_merge_request_diffs`

`get_merge_request_file_diff`

`get_merge_request_note`

`get_merge_request_notes`

`get_merge_request_version`

`get_namespace`

`get_project`

`get_project_events`

`get_protected_branch`

`get_repository_tree`

`get_user`

`get_users`

`health_check`

`list_branches`

`list_ci_catalog_resources`

`list_commit_statuses`

`list_commits`

`list_draft_notes`

`list_events`

`list_group_iterations`

`list_group_members`

`list_group_projects`

`list_issue_discussions`

`list_issue_emoji_reactions`

`list_issue_links`

`list_issue_note_emoji_reactions`

`list_issues`

`list_labels`

`list_merge_request_changed_files`

`list_merge_request_diffs`

`list_merge_request_emoji_reactions`