Skip to main content
Glama
deenesjakoruzh
jmrplens

Gitlab MCP Server

by jmrplens
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Hybrid

GitLab MCP Server

GitHub Release npm PyPI NuGet License: MIT Platform CI Quality Gate Coverage Go Reference

Glama MCP Score

MCP Badge MCP Toplist Cursor Directory Hosted endpoint

All of GitLab for your AI assistant. Up to 1,103 actions over GitLab's REST and GraphQL APIs, from Free to Ultimate and on GitLab.com, in one self-contained binary that works with Claude, Cursor, VS Code, Codex and any other MCP client. You ask in plain language; it does the GitLab work.

11,343 tokens of startup context by default, the same on every GitLab tier (1,941 with GITLAB_MCP_CAPABILITY_SURFACE=minimal). Two tools reach the whole catalog, where listing every tool as its own costs from 576,788 to 734,051 tokens. Measured with the cl100k_base tokenizer and checked in CI. How it is measured

"Review merge request !15: is it safe to merge?" · "Why did the last pipeline fail?" · "List open issues assigned to me" · "Generate release notes from v1.0 to v2.0"

Why this server

  • Every tier and every instance. Free/CE, Premium and Ultimate, self-managed or GitLab.com with its Orbit knowledge graph. The tier is detected and the catalog follows it.

  • The token you already have. A personal, project or group access token with api, or read_api for the actions GitLab accepts from it; a fine-grained token, judged action by action from its grant; OAuth in HTTP mode. Each action's tool reference entry says which scope and which fine-grained permissions it needs.

  • Guard rails. Read-only mode, safe mode (a preview of each write instead of the write), tools excluded by name, and a confirmation before anything destructive.

  • Three surfaces, two transports. Two discovery tools by default, one tool per domain or one per action; stdio for a desktop client, or HTTP for a shared deployment that keeps each credential apart. 45 resources and 37 prompts besides.

  • Releases you can verify. Signed checksums, an SBOM per binary and build provenance for every artifact.

Related MCP server: GitLab MCP Server

Install

The buttons register the Docker image, so they need Docker; the Claude Desktop row downloads a native extension instead. Create a personal access token with the api scope (or read_api for the actions GitLab accepts from it; add GITLAB_MCP_READ_ONLY=true when nothing may be written).

Claude Code. The registration command never carries the token: -e GITLAB_TOKEN forwards it from the environment Claude Code hands docker.

export GITLAB_TOKEN=glpat-xxxx
claude mcp add gitlab --transport stdio \
  -- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest

Any other client runs one of these as the server's command, with GITLAB_TOKEN in the environment it passes:

npx -y @jmrp.io/gitlab-mcp-server                   # npm, nothing installed first
uvx jmrplens-gitlab-mcp-server                      # PyPI, nothing installed first
dnx gitlab-mcp-server                               # NuGet (.NET 10 SDK), nothing installed first
brew install jmrplens/tap/gitlab-mcp-server         # Homebrew, macOS and Linux
winget install --id jmrplens.gitlab-mcp-server -e   # winget, Windows
docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest

For a self-managed instance, set GITLAB_URL=https://gitlab.example.com beside the token; with the Docker image, also forward it by adding -e GITLAB_URL to the docker arguments, since the container receives only the variables named there (Docker install). Every channel, per-client configuration and verification step is in the installation guide, and an assistant installing it for you will find the same in llms.txt.

To try it first, a public instance runs at https://mcp.jmrp.io/gitlab, and the browser inspector calls it read-only after an OAuth sign-in. Your token and every request pass through that machine, so run it yourself to keep using it; the hosted endpoint page says what it is and is not.

Documentation

Everything else is at docs.jmrp.io/gitlab-mcp-server, in English and Spanish: getting started, configuration, tool surfaces, HTTP server mode, security, privacy and troubleshooting.

Contributing, security and licence

Contributions are welcome here on GitHub; CONTRIBUTING.md describes the workflow, and CODE_OF_CONDUCT.md applies. Report a vulnerability privately, as SECURITY.md describes. The server is MIT licensed (LICENSE).

Maintained by José M. Requena Plens · Project page · Hosted instance: mcp.jmrp.io/gitlab

Available Tools

2 tools
gitlab_execute_actionGitLab Execute ActionA
Destructive
Inspect

Execute one GitLab catalog action by canonical ID or alias. Always pass params as an object. Destructive actions require top-level confirm=true. Use find first only when action or params are unclear. Example: {"action":"issue.list","params":{"project_id":"group/project"}}

NameRequiredDescriptionDefault
actionYesCanonical action ID returned by gitlab_find_action, or a supported compatibility alias, such as project.list, issue.update, or issue.close.
paramsYesRequired action-specific parameters object validated by the selected action schema. Use an empty object for actions with no parameters.
confirmNoSet top-level confirm=true to explicitly approve destructive actions. Do not put confirm inside params for gitlab_execute_action.

Output Schema

NameRequiredDescription
next_stepsNoOptional. Suggested follow-up actions or tool calls for the LLM, contextual to the result.
paginationNoPresent on list actions. A REST list carries the fields below: while `has_more` is true, call again with `page` set to `next_page`, or on a keyset page with `page_token` set to `next_page_token`. A GraphQL list carries cursor fields instead: while `has_next_page` is true, pass `end_cursor` as `after`.

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare destructive, open-world, non-idempotent behavior. The description adds important operational context: destructive actions require top-level confirm=true, confirm must not go inside params, and params must always be an object.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is short, front-loaded with the core operation, and includes a compact example. Every sentence carries routing, parameter, or safety information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a complex action dispatcher, it covers the essential execution vs discovery flow and destructive-action confirmation. With full schema coverage and an output schema, remaining details such as action-specific parameter shape are appropriately delegated to the selected action schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already defines action, params, and confirm. The description adds an example and reinforces that params is an object, but it does not add much beyond the structured parameter documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource: execute one GitLab catalog action by canonical ID or alias. It also distinguishes the tool from its sibling by explaining when to use gitlab_find_action first.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Gives explicit routing guidance: execute when the action/params are known, and use find first only when they are unclear. It also states the confirm requirement for destructive actions, leaving little ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gitlab_find_actionGitLab Find ActionA
Read-onlyIdempotent
Inspect

Search the local GitLab action catalog. Read-only and no GitLab API call. Use when the action ID or params are unclear. Returns schemas, hints, destructive flags, and execute examples. Example: {"query":"issue list"}

NameRequiredDescriptionDefault
limitNoMaximum number of matches to return. Defaults to 20 and is capped at 50.
queryYesSearch terms combining a GitLab domain or resource with a verb, filter, or object name, such as project create, merge request approve, pipeline retry, issue delete, or ci variable. At most 256 characters: a longer query is refused, not truncated.
explainNoWhen true, include deterministic scoring reasons for each returned action. Defaults to false to keep responses compact.

Output Schema

NameRequiredDescription
countYesNumber of returned matches.
queryYesOriginal search query.
resultsYesMatching GitLab catalog actions with schemas and execute examples.

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly/idempotent/non-destructive/openWorld, so the safety profile is covered. The description adds genuinely new context: the lookup is local with no GitLab API call, and it discloses the return contents (schemas, hints, destructive flags, execute examples), which helps an agent understand cost and payoff.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loads the verb and the local/no-API constraint, then the usage condition, then the return payload, ending with a minimal example. Every sentence carries distinct information with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, return values need not be enumerated, yet the description still summarizes them; parameters are fully covered by the schema and the usage trigger is stated. Nothing an agent needs to select or call this tool is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so query/limit/explain are fully documented in the schema itself. The example {"query":"issue list"} is a concrete illustration but adds little beyond the schema's own query-format guidance, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ("Search the local GitLab action catalog") plus scope qualifiers ("local", "no GitLab API call"). The clause "Use when the action ID or params are unclear" functionally separates it from the gitlab_execute_action sibling without needing the schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

"Use when the action ID or params are unclear" gives a clear triggering condition and implies the converse path (use execute when they are clear). It stops short of naming the alternative tool or stating exclusions explicitly, so it is clear context rather than a full routing rule.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv3.3.0
    • Changedgitlab_execute_action7 fields changed
      • changedOutput schema / properties / pagination / description
        Previous value: -"Present on list actions. Use `has_more` and `next_page` to paginate through results."New value: +"Present on list actions. A REST list carries the fields below: while `has_more` is true, call again with `page` set to `next_page`, or on a keyset page with `page_token` set to `next_page_token`. A GraphQL list carries cursor fields instead: while `has_next_page` is true, pass `end_cursor` as `after`."
      • changedOutput schema / properties / pagination / properties / has_more / description
        Previous value: -"True when more pages are available after the current one."New value: +"True when GitLab named a next page: `next_page` on an offset page, `next_page_token` on a keyset page. A keyset link can lead to one empty page after the last rows."
      • changedOutput schema / properties / pagination / properties / next_page / description
        Previous value: -"Next page index when `has_more` is true."New value: +"Next page index on an offset page that has a successor. It is 0 on the last page and on every keyset page, whose successor is `next_page_token`."
      • addedOutput schema / properties / pagination / properties / next_page_token
        Added value: +{
+  "description": "On a page GitLab served by keyset pagination, which names no next_page, the value to pass back unchanged as `page_token` for the next page. Absent otherwise.",
+  "type": "string"
+}
      • removedOutput schema / properties / pagination / properties / total
        Removed value: -{
-  "description": "Total item count when known (some endpoints omit it for performance).",
-  "type": "integer"
-}
      • addedOutput schema / properties / pagination / properties / total_items
        Added value: +{
+  "description": "Items across all pages, 0 when GitLab sends no total.",
+  "type": "integer"
+}
      • changedOutput schema / properties / pagination / properties / total_pages / description
        Previous value: -"Total page count when known."New value: +"Pages in all, 0 when GitLab sends no total."
    • Changedgitlab_find_action1 field changed
      • addedOutput schema / properties / results / items / properties / required_params_any_of
        Added value: +{
+  "description": "Alternative groups: a call also needs every name of one group, not all groups.",
+  "items": {
+    "items": {
+      "type": "string"
+    },
+    "type": [
+      "null",
+      "array"
+    ]
+  },
+  "type": [
+    "null",
+    "array"
+  ]
+}
  2. 2 tool updatesv3.0.0
    • Changedgitlab_execute_action1 field changed
      • changedInput schema / properties / confirm / description
        Previous value: -"Set top-level confirm=true to explicitly approve destructive actions; do not put confirm inside params for gitlab_execute_action."New value: +"Set top-level confirm=true to explicitly approve destructive actions. Do not put confirm inside params for gitlab_execute_action."
    • Changedgitlab_find_action2 fields changed
      • changedInput schema / properties / query / description
        Previous value: -"Search terms combining a GitLab domain or resource with a verb, filter, or object name, such as project create, merge request approve, pipeline retry, issue delete, or ci variable."New value: +"Search terms combining a GitLab domain or resource with a verb, filter, or object name, such as project create, merge request approve, pipeline retry, issue delete, or ci variable. At most 256 characters: a longer query is refused, not truncated."
      • addedInput schema / properties / query / maxLength
        Added value: +256
  3. 1 tool updatev2.7.5
    • Changedgitlab_execute_action1 field changed
      • changedInput schema / properties / action / x-mcp-header
        Previous value: -"Mcp-Param-Action"New value: +"Action"
  4. 1 tool updatev2.6.0
    • Addedgitlab_execute_action
  5. 1 tool updatev2.5.2
    • Removedgitlab_execute_action
  6. 3 tool updatesv2.1.3
    • Addedgitlab_execute_action
    • Removedgitlab_execute_tool
    • Changedgitlab_find_action4 fields changed
      • changedOutput schema / properties / results / items / properties / example / description
        Previous value: -"Example gitlab_execute_tool call."New value: +"Example gitlab_execute_action call."
      • changedOutput schema / properties / results / items / properties / example / properties / arguments / description
        Previous value: -"Example arguments for gitlab_execute_tool."New value: +"Example arguments for gitlab_execute_action."
      • changedOutput schema / properties / results / items / properties / id / description
        Previous value: -"Canonical action ID to pass to gitlab_execute_tool."New value: +"Canonical action ID to pass to gitlab_execute_action."
      • changedOutput schema / properties / results / items / properties / required_params / description
        Previous value: -"Required parameter names captured from the input schema."New value: +"Required action-specific parameter names to place inside gitlab_execute_action params."
Deploy Server
Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

TDQS

A4.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct roles: gitlab_find_action is read-only catalog search, while gitlab_execute_action performs an action. There is no ambiguity about which tool to use, and the descriptions explicitly state when to use each.

Naming Consistency5/5

Both names follow the same gitlab_<verb>_action pattern, using consistent snake_case and predictable verbs (find, execute). The convention is immediately clear across the set.

Tool Count4/5

Two tools is thin in absolute terms, but here they act as a deliberate gateway exposing a large GitLab action catalog. The meta-tool pattern keeps the surface small and well-scoped rather than being an underbuilt server.

Completeness4/5

The execute tool can run any canonical catalog action, and the find tool supports discovery with schemas and hints, so the surface is broad and lifecycle coverage depends on the catalog. Minor gaps may exist if the catalog is incomplete, but destructive-action confirmation and discovery are handled.

Maintenance

ActivityActive
ResponsivenessResponsive

Resources

Related MCP Connectors

Related MCP Servers

  • GitLab MCP Server

    ZephyrDeng
    -
    license
    Not graded
    quality
    Not graded
    maintenance
    A Model Context Protocol server that enables AI assistants to interact with GitLab repositories, allowing tasks like managing merge requests, searching projects, and creating comments through RESTful API integration.
    12 npm
    2
    -

  • mcp-gitlab-jira

    HainanZhao
    A
    license
    B
    quality
    C
    maintenance
    A Model Context Protocol (MCP) server for GitLab and Jira integration. This server allows AI agents like gemini-cli to interact with your GitLab and Jira instances.
    32
    15 npm
    11
    MIT

  • gitlab-mcp

    structured-world
    A
    license
    Not graded
    quality
    A
    maintenance
    Full-coverage GitLab MCP server with 44 tools across 18 resource types. Agent-optimized CQRS design — one tool call handles complete multi-step operations. Supports OAuth 2.1, read-only mode, stdio/SSE/StreamableHTTP transports, and GraphQL-native work items with full hierarchy (epics,issues,etc)
    1,922 npm
    8
    Apache 2.0