Skip to main content
Glama
GitLab MCP Server

GitLab MCP Server

by ttpears

GitLab MCP Server

npm version CI License: MIT

A community Model Context Protocol server that lets AI clients search GitLab, read repositories, review merge requests, manage issues, and summarize team activity. Supports GitLab.com and self-managed GitLab through stdio and Streamable HTTP.

This project is independent of GitLab Inc. It does not require GitLab Duo. Individual tools remain subject to your GitLab version, tier, enabled features, token scopes, and role.

Start locally

Requires Node.js 22 or later. CI covers Node.js 22 and 24; the container uses Node.js 24.

  1. Create a GitLab personal access token with read_api for reads or api for reads and writes. The token can only access resources its owner is allowed to use.

  2. Add this server to your client's MCP configuration. Replace the token locally; keep the resulting file out of version control.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@ttpears/gitlab-mcp-server@4.0.0"],
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_READ_TOKEN": "glpat-replace-locally"
      }
    }
  }
}
  1. Restart or reconnect the client. Ask it to call get_current_user, then search_projects with {"searchTerm":"your-project","first":5}.

For writes, replace GITLAB_READ_TOKEN with GITLAB_TOKEN and use an api-scoped token. Setting both variables is a startup error. Stdio is the default; it communicates over stdin/stdout and does not open a listening port.

Related MCP server: GitLab MR MCP

Choose a setup

Use case

Setup

Claude Code, Claude Desktop, VS Code, or another local client

Client installation

Claude Desktop bundle

Download gitlab-mcp-community-4.0.0.mcpb from the 4.0.0 release

LibreChat with each user's PAT

LibreChat guide and YAML example

Shared remote server with GitLab sign-in

OAuth setup

Docker or a reverse proxy

Deployment and operations

Existing installation

Upgrade to 4.0

For a local HTTP smoke test without a shared token:

docker run --rm --name gitlab-mcp \
  -p 127.0.0.1:8008:8008 \
  -e GITLAB_URL=https://gitlab.com \
  ghcr.io/ttpears/gitlab-mcp:4.0.0

Connect an MCP client to http://localhost:8008/ and send Authorization: Bearer <your-GitLab-PAT> on every request. curl http://localhost:8008/health checks liveness. The published image currently targets Linux amd64. Configure HTTPS and user authentication before remote use; see the deployment guide.

What you can do

The server exposes 69 tools and 8 workflow prompts. The tool reference lists every tool, its input parameters, defaults, and write classification.

Task

Start with

Find projects, groups, users, issues, or merge requests

search_projects, search_groups, search_users, search_issues, search_merge_requests

Identify a path and inspect code

resolve_path, browse_repository, get_file_content

Review a change and its CI results

get_merge_request_context, get_merge_request_diffs, get_merge_request_pipelines, get_pipeline_jobs

Triage and update work

get_issue_context, create_issue, update_issue, create_note, update_merge_request

Work with planning and notifications

list_milestones, list_iterations, list_work_items, list_my_todos

Summarize activity and review delays

analytics_user_summary, analytics_group_summary, analytics_review_bottlenecks

Manage group achievements

list_achievements, create_achievement, award_achievement

Discover instance-specific API capabilities

get_available_queries, get_type_fields

Try: “Find open bugs assigned to me,” “Review MR !42 in group/project,” or “Summarize this group's activity since Monday.” See workflows and pagination for exact tool-call examples and prompt names.

Read before sharing a server

  • GITLAB_TOKEN is a fallback for reads and writes. GITLAB_READ_TOKEN is a fallback for reads only. A shared fallback exposes that account's accessible data to callers using it.

  • With neither fallback set, each operation needs user credentials through an HTTP PAT, OAuth, or userCredentials.

  • Host pinning, finite resource limits, and restrictions on custom GraphQL/REST tools are enabled by default. Tool annotations are client hints; GitLab permissions and the server's credential checks enforce access.

  • fetchAll: true fetches up to first items. For complete results, keep following each connection's pageInfo.endCursor while hasNextPage is true.

See authentication and security for credential precedence, OAuth consent, encrypted Redis storage, and access boundaries.

Documentation

Field notes: Two session bugs that broke my GitLab MCP server.

Licensed under MIT.

Available Tools

69 tools
analytics_group_summaryGroup Activity SummaryA
Read-onlyIdempotent

Aggregated activity summary for an entire group (optionally including subgroups) over a time window — totals by action type (pushes, MRs opened/merged, comments, approvals), with breakdowns by project, by contributor, and by day. Use this to answer "what did this team do" without fanning out across list_project_events yourself.

Inputs: group (required), since (required), until, maxEvents, +4 more.

analytics_review_bottlenecksReview BottlenecksA
Read-onlyIdempotent

Aggregate open (non-draft) merge requests across a group or project to surface review bottlenecks. Returns per-reviewer queue stats, age-bucket histogram, and the stalest MRs by updatedAt. MRs with no reviewer assigned are bucketed under "(unassigned)".

Inputs: group, maxMRs, project, topStalest, +2 more.

analytics_user_summaryUser Activity SummaryA
Read-onlyIdempotent

Aggregated activity summary for a user over a time window — totals by action type (pushes, MRs opened/merged, comments, approvals), breakdown by project and by day. Use this instead of list_user_events when you want counts rather than a raw event feed.

Inputs: user (required), since (required), until, maxEvents, +1 more.

award_achievementAward AchievementA

Award an achievement to a GitLab username. Multiple awards to the same user are allowed. Requires group Maintainer/Owner. GitLab notifies the recipient, who may need to accept before it appears on their profile.

Inputs: username (required), achievementId (required), awardMessage, userCredentials.

browse_repositoryBrowse RepositoryB
Read-onlyIdempotent

Browse repository files and folders - essential for exploring codebase structure

Inputs: projectPath (required), ref, path, userCredentials.

create_achievementCreate AchievementA

Create a group achievement with name and optional description. Requires group Maintainer/Owner and enabled Achievements. Set avatars in GitLab UI; file uploads are not supported by this tool.

Inputs: name (required), group (required), description, userCredentials.

create_broadcast_messageCreate Broadcast MessageA

Create a GitLab broadcast message. Requires administrator privileges on the GitLab instance.

Inputs: message (required), font, color, theme, +7 more.

create_issueCreate IssueA

Create a new issue in a GitLab project (requires user authentication with write permissions)

Inputs: title (required), projectPath (required), description, userCredentials. Returns: id, iid, title, webUrl

create_merge_requestCreate Merge RequestB

Create a new merge request in a GitLab project (requires user authentication with write permissions)

Inputs: title (required), projectPath (required), sourceBranch (required), targetBranch (required), +2 more. Returns: id, iid, title, webUrl

create_noteCreate NoteB

Add a comment/note to an issue or merge request (requires user authentication)

Inputs: iid (required), body (required), projectPath (required), noteableType (required), +2 more.

delete_achievementDelete AchievementA
DestructiveIdempotent

Delete a group achievement and every related awarded or revoked instance. Destructive; requires group Maintainer/Owner.

Inputs: achievementId (required), userCredentials.

delete_broadcast_messageDelete Broadcast MessageA
DestructiveIdempotent

Delete a GitLab broadcast message by ID. Requires administrator privileges.

Inputs: id (required), userCredentials.

delete_issueDelete IssueA
DestructiveIdempotent

Delete a GitLab issue. Requires a user token with permission to delete issues in the project (typically the issue author or a maintainer).

Inputs: iid (required), projectPath (required), userCredentials.

delete_noteDelete NoteA
DestructiveIdempotent

Delete a comment (note) on a GitLab issue or merge request. Requires a user token belonging to the note author or a maintainer.

Inputs: noteId (required), userCredentials.

execute_custom_queryCustom GraphQL QueryA

Execute custom GraphQL queries for complex filtering (e.g., issues with assigneeUsernames: ["user"], labelName: ["bug"]). Use this for structured filtering by assignee/author/labels when search tools return 0 results. Use pagination and limit complexity to avoid timeouts.

Inputs: query (required), variables, requiresWrite, userCredentials.

execute_rest_readCustom REST ReadA
Read-onlyIdempotent

Execute an arbitrary GET request against the GitLab REST API at /api/v4. Open-ended escape hatch for read endpoints not covered by a dedicated tool — e.g. /projects/:id/repository/files, /projects/:id/pipelines/:pipeline_id/test_report, /admin/*. Provide the path beginning with "/" (no host, no /api/v4 prefix) and an optional query object. For writes, use execute_rest_write.

Inputs: path (required), query, userCredentials.

execute_rest_writeCustom REST WriteA
Destructive

Execute an arbitrary POST/PUT/PATCH/DELETE request against the GitLab REST API at /api/v4. Open-ended escape hatch for write endpoints not covered by a dedicated tool. Destructive — DELETE is permitted, so check the path before invoking. For reads, use execute_rest_read.

Inputs: path (required), method (required), body, query, +1 more.

get_available_queriesAvailable QueriesC
Read-onlyIdempotent

Get list of available GraphQL queries and mutations from the GitLab schema

Inputs: userCredentials.

get_broadcast_messageGet Broadcast MessageA
Read-onlyIdempotent

Get a specific GitLab broadcast message by ID.

Inputs: id (required), userCredentials.

get_current_userCurrent UserA
Read-onlyIdempotent

Get information about the current authenticated GitLab user

Inputs: userCredentials. Returns: id, name, username

get_file_contentFile ContentC
Read-onlyIdempotent

Get the content of a specific file from a GitLab repository - crucial for code analysis

Inputs: filePath (required), projectPath (required), ref, userCredentials.

get_group_projectsGroup ProjectsC
Read-onlyIdempotent

List projects inside a GitLab group (optionally filter by search term)

Inputs: fullPath (required), after, first, searchTerm, +1 more.

get_issue_contextGet Issue ContextA
Read-onlyIdempotent

Bundle issue body, all notes (paginated up to maxNotes), related merge requests (mentioning), closing merge requests, linked issues (relates_to/blocks/is_blocked_by) into a single call. Use this instead of fanning out across get_issues + get_notes + search_merge_requests when investigating an issue.

Inputs: iid (required), projectPath (required), maxNotes, userCredentials, +1 more.

get_issuesProject IssuesC
Read-onlyIdempotent

Get issues from a specific GitLab project (read-only)

Inputs: projectPath (required), sort, after, first, +2 more. Returns: nodes, hasMore, pageInfo, totalFetched

get_merge_request_commitsMR CommitsA
Read-onlyIdempotent

Get commits for a merge request (excluding merge commits), with commit count and details

Inputs: iid (required), projectPath (required), after, first, +2 more.

get_merge_request_contextGet Merge Request ContextA
Read-onlyIdempotent

Bundle MR body, all notes (paginated up to maxNotes, filtered to non-system by default), commits, pipeline summary, reviewers with approval state, and issues this MR will close into a single call. Use this instead of fanning out across get_merge_requests + get_notes + get_merge_request_commits + get_merge_request_pipelines when investigating an MR.

Inputs: iid (required), projectPath (required), maxNotes, maxCommits, +2 more.

get_merge_request_diffsMR DiffsB
Read-onlyIdempotent

Get diff statistics for a merge request, including per-file additions/deletions and diff refs

Inputs: iid (required), projectPath (required), userCredentials.

get_merge_request_pipelinesMR PipelinesB
Read-onlyIdempotent

Get CI/CD pipelines for a merge request, including status, duration, and stages

Inputs: iid (required), projectPath (required), after, first, +2 more.

get_merge_request_reviewersMR ReviewersA
Read-onlyIdempotent

Get approval and reviewer status for a merge request, including who approved and review states

Inputs: iid (required), projectPath (required), userCredentials.

get_merge_requestsMerge RequestsC
Read-onlyIdempotent

Get merge requests from a specific GitLab project (read-only)

Inputs: projectPath (required), sort, after, first, +2 more. Returns: nodes, hasMore, pageInfo, totalFetched

get_notesNotes/CommentsB
Read-onlyIdempotent

Get notes (comments) on an issue or merge request, including system notes and inline MR comments

Inputs: iid (required), projectPath (required), noteableType (required), after, +3 more.

get_pipeline_jobsPipeline JobsA
Read-onlyIdempotent

Get jobs for a specific pipeline, including status, stage, duration, and retry/cancel info

Inputs: pipelineIid (required), projectPath (required), after, first, +2 more.

get_projectProject DetailsC
Read-onlyIdempotent

Get detailed information about a specific GitLab project (read-only)

Inputs: fullPath (required), userCredentials. Returns: id, name, webUrl, fullPath

get_projectsList ProjectsB
Read-onlyIdempotent

List projects accessible to the user (requires authentication to see private projects)

Inputs: sort, after, first, fetchAll, +1 more. Returns: nodes, hasMore, pageInfo, totalFetched

get_project_statisticsProject StatisticsA
Read-onlyIdempotent

Get aggregate project statistics: open issues/MRs, star/fork counts, storage sizes, commit count, last pipeline status, release count, and language breakdown

Inputs: projectPath (required), userCredentials.

get_time_trackingTime TrackingA
Read-onlyIdempotent

Get time tracking data (estimate, spent, timelogs) for an issue or merge request

Inputs: iid (required), projectPath (required), resourceType (required), after, +3 more.

get_type_fieldsGraphQL Type FieldsA
Read-onlyIdempotent

List available fields on a GraphQL type using introspected schema (requires schema to be introspected)

Inputs: typeName (required), userCredentials.

get_user_issuesUser IssuesB
Read-onlyIdempotent

Get all issues assigned to a specific user - uses proper GraphQL filtering for reliable results

Inputs: username (required), after, first, state, +3 more.

get_user_merge_requestsUser Merge RequestsC
Read-onlyIdempotent

Get merge requests for a specific user (as author or assignee) - uses proper GraphQL filtering

Inputs: username (required), role, after, first, +4 more.

get_work_itemGet Work ItemA
Read-onlyIdempotent

Fetch a GitLab work item (issue, task, epic, incident, OKR) by global ID. Returns the raw widgets array so epic hierarchy, health status, iteration, milestone, and dates are all visible. Accepts either a numeric id or a full gid (gid://gitlab/WorkItem/123).

Inputs: id (required), userCredentials.

list_achievementsList AchievementsA
Read-onlyIdempotent

List group achievements with cursor pagination. Requires Achievements to be enabled on the GitLab instance. Optional recipient previews are a single page per achievement; each preview includes pageInfo.

Inputs: group (required), ids, after, first, +3 more.

list_broadcast_messagesList Broadcast MessagesA
Read-onlyIdempotent

List all GitLab broadcast messages (instance-wide announcements). Read-only.

Inputs: page, perPage, userCredentials.

list_group_membersGroup MembersA
Read-onlyIdempotent

List group members with access levels, optionally filtered by search term

Inputs: groupPath (required), after, first, search, +2 more.

list_iterationsIterationsA
Read-onlyIdempotent

List iterations (sprints) for a group with cadence info. Requires GitLab Premium/Ultimate.

Inputs: groupPath (required), after, first, state, +2 more.

list_milestonesMilestonesA
Read-onlyIdempotent

List milestones for a project or group with progress statistics (total/closed issue counts)

Inputs: fullPath (required), isProject (required), after, first, +5 more.

list_my_eventsMy EventsB
Read-onlyIdempotent

List the authenticated user's GitLab activity feed — pushes, MRs, comments, approvals, issue actions. Primary tool for "what did I just do". Requires user authentication.

Inputs: page, sort, after, scope, +5 more.

list_my_todosMy TodosA
Read-onlyIdempotent

List the authenticated user's GitLab to-do items (notifications about issues, MRs, mentions, reviews requested, etc.). Filter by state, action, target type, or group/project. Requires user authentication.

Inputs: sort, type, after, first, +8 more.

list_project_eventsProject EventsA
Read-onlyIdempotent

List activity events for a single GitLab project — commits pushed, MRs opened/merged, issues touched, notes added. Accepts project full path or numeric ID.

Inputs: project (required), page, sort, after, +5 more.

list_user_eventsUser EventsA
Read-onlyIdempotent

List a specific user's public GitLab activity feed by username or numeric ID. Use for tracking what a teammate has been working on.

Inputs: user (required), page, sort, after, +5 more.

list_work_itemsList Work ItemsA
Read-onlyIdempotent

List work items within a namespace (group or project fullPath). Supports filtering by type (ISSUE, TASK, EPIC, INCIDENT, OBJECTIVE, KEY_RESULT) and state, plus cursor pagination and fetchAll.

Inputs: fullPath (required), sort, after, first, +4 more.

manage_pipelineManage PipelineA

Retry or cancel a CI/CD pipeline (requires user authentication with write permissions)

Inputs: action (required), pipelineIid (required), projectPath (required), userCredentials.

mark_all_todos_doneMark All Todos DoneA
DestructiveIdempotent

Mark pending to-do items as done for the authenticated user. With no arguments, marks every pending todo. Optional scoping args (groupPath, projectPath, action, type, authorIds, targetId) narrow which todos are marked. Irreversible without per-item restore_todo calls. Returns the actual list of updated todos.

Inputs: type, action, targetId, authorIds, +3 more.

mark_todo_doneMark Todo DoneA
Idempotent

Mark a single to-do item as done for the authenticated user. Requires the todo's ID (numeric or full gid://gitlab/Todo/N form) from list_my_todos.

Inputs: todoId (required), userCredentials.

resolve_pathResolve PathB
Read-onlyIdempotent

Resolve a GitLab path to either a project or group and list group projects when applicable

Inputs: fullPath (required), after, first, userCredentials.

restore_todoRestore TodoA
Idempotent

Restore a previously-marked-done to-do item back to pending state. Accepts the todo's ID (numeric or full gid://gitlab/Todo/N form).

Inputs: todoId (required), userCredentials.

revoke_achievementRevoke AchievementA
DestructiveIdempotent

Revoke one awarded achievement. Provide either userAchievementId, or group + achievementId + username. Username lookup scans recipient pages and rejects ambiguous repeated awards; use a specific userAchievementId in that case. Requires group Maintainer/Owner.

Inputs: group, username, achievementId, userCredentials, +1 more.

search_gitlabSearch GitLabA
Read-onlyIdempotent

Text search across GitLab projects and issues (Note: Does not support filtering by assignee/labels - use search_issues for that. MRs cannot be searched globally - use search_merge_requests with username)

Inputs: after, first, fetchAll, searchTerm, +1 more.

search_groupsSearch GroupsC
Read-onlyIdempotent

Search for GitLab groups and organizations

Inputs: searchTerm (required), after, first, fetchAll, +1 more.

search_issuesSearch IssuesB
Read-onlyIdempotent

Search for issues with text search and/or structured filtering (assignee, author, labels, state). For filtering by assignee/author/labels without text search, leave searchTerm empty.

Inputs: sort, after, first, state, +7 more. Returns: nodes, hasMore, pageInfo, totalFetched

search_labelsSearch LabelsB
Read-onlyIdempotent

Search for labels in a project or group, with optional text filtering

Inputs: fullPath (required), isProject (required), after, first, +3 more.

search_merge_requestsSearch Merge RequestsA
Read-onlyIdempotent

Search merge requests by username (supports "username", "author:username", "assignee:username") or search within a specific project. Note: GitLab does not support global text search for MRs - use projectPath for text searches.

Inputs: searchTerm (required), sort, after, first, +4 more. Returns: nodes, hasMore, pageInfo, totalFetched

search_notesSearch Notes (Comments)A
Read-onlyIdempotent

Full-text search across issue and merge request comments. Scope can be global, a project, or a group. NOTE: on self-hosted GitLab, the "notes" search scope requires Advanced Search (Elasticsearch) to be enabled — without it, this endpoint returns an error. search_gitlab does NOT search note bodies; this tool does.

Inputs: search (required), page, scope, perPage, +3 more.

search_projectsSearch ProjectsC
Read-onlyIdempotent

Search for GitLab projects by name or description

Inputs: searchTerm (required), after, first, fetchAll, +1 more. Returns: nodes, hasMore, pageInfo, totalFetched

search_usersSearch UsersB
Read-onlyIdempotent

Search for GitLab users by username or name - useful for finding team members or contributors

Inputs: searchTerm (required), after, first, fetchAll, +1 more.

update_achievementUpdate AchievementA
Idempotent

Update an achievement name or description. Requires group Maintainer/Owner. Provide at least one changed field; an empty description clears it.

Inputs: achievementId (required), name, description, userCredentials.

update_broadcast_messageUpdate Broadcast MessageB
Idempotent

Update an existing GitLab broadcast message. Requires administrator privileges.

Inputs: id (required), font, color, theme, +8 more.

update_issueUpdate IssueB
Idempotent

Update an issue (title, description, assignees, labels, due date) with schema-aware mutations

Inputs: iid (required), projectPath (required), title, dueDate, +4 more.

update_merge_requestUpdate Merge RequestB
Idempotent

Update a merge request (title, description, assignees, reviewers, labels) with schema-aware mutations

Inputs: iid (required), projectPath (required), title, labelNames, +4 more.

update_noteUpdate NoteA
Idempotent

Edit the body of an existing comment (note) on a GitLab issue or merge request. Requires a user token belonging to the note author.

Inputs: body (required), noteId (required), userCredentials.

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    B3.1/5.0

    Scored across 69 tools

    Disambiguation3/5

    There are several overlapping retrieval paths—get_issues/search_issues/get_user_issues/list_work_items/get_issue_context for issues and analogous merge request tools—plus get_notes vs search_notes and dedicated tools vs execute_rest_read/execute_custom_query. Descriptions generally explain when to use which, so boundaries are recoverable, but the set still invites misselection.

    Naming Consistency4/5

    Almost all tools use snake_case verb_noun naming such as get_project, create_issue, delete_note, and search_merge_requests. Minor deviations like analytics_user_summary, execute_rest_read, and mark_all_todos_done are readable and do not break the overall pattern.

    Tool Count1/5

    69 tools is far beyond a well-scoped MCP surface and includes many specialized, overlapping, and escape-hatch tools. This creates a large selection burden for an agent and is an extreme mismatch for typical usage.

    Completeness3/5

    Core issue, merge request, note, pipeline, todo, event, achievement, and broadcast workflows are covered, and generic REST/GraphQL escape hatches prevent total dead ends. However, common GitLab operations like project/group CRUD, label/milestone lifecycle, branches, and file writes lack dedicated tools, so coverage is only partial.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with GitLab repositories through secure OAuth 2.0 authentication. Supports comprehensive GitLab operations including merge requests, issues, file management, commits, and branch operations through natural language.
      12 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with GitLab repositories, manage merge requests, review code diffs, post comments, and handle issues directly through natural language.
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to interact with GitLab repositories, monitor documentation changes, manage issues and merge requests, and search across projects with comprehensive file and commit operations.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with GitLab for managing projects, branches, issues, and merge requests. It provides tools for searching code and performing file operations like reading and writing directly within repositories.
      26 npm
      MIT