Summary
Hooks into the GitLab REST API v4 and GraphQL to expose 1000+ operations as MCP tools, from merge request creation and pipeline inspection to wiki edits and container registry management. Ships as a single static binary with three transport modes: stdio for local Claude Desktop, streamable HTTP for remote setups, and a dynamic find/execute surface that keeps token overhead under 21k while maintaining full API reach. Built with security scanning on SonarCloud and supports self-hosted GitLab instances with TLS verification. Includes 11 sampling actions for LLM-assisted code review and pipeline failure diagnosis, plus 46 resources for read-only access to projects, issues, and commits. Reach for this when you need programmatic GitLab control from an AI assistant without clicking through the web UI.
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →
Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Tools
Public tool metadata for what this MCP can expose to an agent.
54 tools
GITLAB_ARCHIVE_PROJECTTool to archive a project. Use when you need to mark a project read-only after finishing active development. Call after confirming no further changes are required.1 params
Tool to archive a project. Use when you need to mark a project read-only after finishing active development. Call after confirming no further changes are required.
Parameters* required
idintegerThe ID or URL-encoded path of the project to archive.
GITLAB_CREATE_GROUPTool to create a new group in GitLab. Use when you need to establish a new group for projects or collaboration.26 params
Tool to create a new group in GitLab. Use when you need to establish a new group for projects or collaboration.
Parameters* required
auto_devops_enabledbooleanDefault to Auto DevOps pipeline for all projects within this group.
avatarstringImage file for avatar of the group.
default_branchstringThe default branch name for group’s projects.
default_branch_protection_defaultsobjectOptions for default_branch_protection_defaults. E.g. {"allowed_to_push": [{"access_level":40}], "allow_force_push": False, "allowed_to_merge": [{"access_level":40}], "developer_can_initial_push": F...
descriptionstringThe group’s description.
duo_availabilitystringDuo availability setting. Note: In the UI, never_on is displayed as "Always Off".one of
default_on · default_off · never_onemails_enabledbooleanEnable email notifications.
enabled_git_access_protocolstringEnabled protocols for Git access.one of
ssh · http · allexperiment_features_enabledbooleanEnable experiment features for this group.
extra_shared_runners_minutes_limitintegerCan be set by administrators only. Additional compute minutes for this group. GitLab Self-Managed, Premium and Ultimate only.
lfs_enabledbooleanEnable/disable Large File Storage (LFS) for the projects in this group.
membership_lockbooleanUsers cannot be added to projects in this group. Premium and Ultimate only.
mentions_disabledbooleanDisable the capability of a group from getting mentioned.
namestringThe name of the group.
organization_idintegerThe organization ID for the group.
parent_idintegerThe parent group ID for creating nested group.
pathstringThe path of the group.
project_creation_levelstringDetermine if developers can create projects in the group.one of
administrator · noone · maintainer · developerrequest_access_enabledbooleanAllow users to request member access.
require_two_factor_authenticationbooleanRequire all users in this group to set up two-factor authentication.
+6 more parameters. See the server's own documentation for the full schema.
GITLAB_CREATE_PROJECTTool to create a new project in GitLab. Implements POST /projects endpoint.12 params
Tool to create a new project in GitLab. Implements POST /projects endpoint.
Parameters* required
build_git_strategystringGit strategy for builds.
container_registry_enabledbooleanEnable container registry.
default_branchstringThe default branch name.
descriptionstringProject description.
issues_enabledbooleanEnable issues feature.
merge_requests_enabledbooleanEnable merge requests feature.
namestringThe name of the project.
namespace_idintegerThe namespace (group or user ID) under which to create the project.
pathstringThe path or URL-friendly name for the project.
snippets_enabledbooleanEnable snippets feature.
visibilitystringProject visibility.one of
private · internal · publicwiki_enabledbooleanEnable wiki feature.
GITLAB_CREATE_PROJECT_ISSUETool to create a new issue in a GitLab project. Use when you need to report a bug, request a feature, or track a task within a specific project.17 params
Tool to create a new issue in a GitLab project. Use when you need to report a bug, request a feature, or track a task within a specific project.
Parameters* required
assignee_idintegerThe ID of the user to assign the issue to. Only appears on GitLab Free.
assignee_idsarrayThe IDs of the users to assign the issue to. Premium and Ultimate only.
confidentialbooleanSet an issue to be confidential. Default is false.default: false
created_atstringWhen the issue was created. Date time string, ISO 8601 formatted, for example `2016-03-11T03:45:40Z`. Requires administrator or project/group owner rights.
descriptionstringThe description of an issue. Limited to 1,048,576 characters.
discussion_to_resolvestringThe ID of a discussion to resolve. This fills out the issue with a default description and mark the discussion as resolved. Use in combination with `merge_request_to_resolve_discussions_of`.
due_datestringThe due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`.
epic_idintegerID of the epic to add the issue to. Valid values are greater than or equal to 0. Premium and Ultimate only.
epic_iidintegerIID of the epic to add the issue to. Valid values are greater than or equal to 0. (deprecated, scheduled for removal in API version 5). Premium and Ultimate only.
idstringThe global ID or URL-encoded path of the project.
iidintegerThe internal ID of the project’s issue (requires administrator or project owner rights).
issue_typestringThe type of issue. One of `issue`, `incident`, `test_case` or `task`. Default is `issue`.one of
issue · incident · test_case · taskdefault: issuelabelsstringComma-separated label names to assign to the new issue. If a label does not already exist, this creates a new project label and assigns it to the issue.
merge_request_to_resolve_discussions_ofintegerThe IID of a merge request in which to resolve all issues. This fills out the issue with a default description and mark all discussions as resolved. When passing a description or title, these value...
milestone_idintegerThe global ID of a milestone to assign issue. To find the `milestone_id` associated with a milestone, view an issue with the milestone assigned and use the API to retrieve the issue’s details.
titlestringThe title of an issue.
weightintegerThe weight of the issue. Valid values are greater than or equal to 0. Premium and Ultimate only.
GITLAB_CREATE_REPOSITORY_BRANCHTool to create a new branch in a project. Use when you need to create a new branch from an existing branch or a specific commit in a GitLab project.3 params
Tool to create a new branch in a project. Use when you need to create a new branch from an existing branch or a specific commit in a GitLab project.
Parameters* required
branch_namestringThe name of the new branch.
project_idintegerThe ID or URL-encoded path of the project.
refstringThe branch name or commit SHA to create the new branch from.
GITLAB_DELETE_PROJECTTool to delete a GitLab project by its ID. Use when you need to remove a project, either by marking it for later deletion or deleting it immediately.3 params
Tool to delete a GitLab project by its ID. Use when you need to remove a project, either by marking it for later deletion or deleting it immediately.
Parameters* required
full_pathstringThe full path of the project (e.g., namespace/project_name). Used with `permanently_remove=true` for immediate deletion. Available in GitLab Free from 18.0 (previously Premium/Ultimate only since 1...
idintegerThe ID or URL-encoded path of the project to be deleted.
permanently_removebooleanIf true, the project is deleted immediately. Otherwise, it is marked for deletion and removed after a retention period. Available in GitLab Free from 18.0 (previously Premium/Ultimate only since 15...
GITLAB_DOWNLOAD_PROJECT_AVATARTool to download a project’s avatar image. Use when you need the raw avatar bytes after confirming the project exists.1 params
Tool to download a project’s avatar image. Use when you need the raw avatar bytes after confirming the project exists.
Parameters* required
idstringThe ID or URL-encoded path of the project whose avatar to download.
GITLAB_ERASE_JOBTool to erase the content of a specified job within a project. Use when you need to remove job artifacts and logs.2 params
Tool to erase the content of a specified job within a project. Use when you need to remove job artifacts and logs.
Parameters* required
job_idintegerThe ID of the job to be erased.
project_idintegerThe ID or URL-encoded path of the project.
GITLAB_GET_COMMIT_REFSTool to get all references (branches or tags) a commit is pushed to. Use when you need to find out which branches or tags a specific commit belongs to in a GitLab project.3 params
Tool to get all references (branches or tags) a commit is pushed to. Use when you need to find out which branches or tags a specific commit belongs to in a GitLab project.
Parameters* required
project_idintegerThe ID or URL-encoded path of the project.
ref_typestringThe scope of commits to list. Possible values are `branch`, `tag`, or `all`.one of
branch · tag · alldefault: allshastringThe commit hash.
GITLAB_GET_COMMIT_SEQUENCETool to get the sequence number of a commit in a project by following parent links from the given commit. Use when you need to determine the order of a commit in the project's history.3 params
Tool to get the sequence number of a commit in a project by following parent links from the given commit. Use when you need to determine the order of a commit in the project's history.
Parameters* required
first_parentbooleanFollow only the first parent commit upon seeing a merge commit.
project_idintegerThe ID or URL-encoded path of the project.
shastringThe commit hash.
GITLAB_GET_GROUPTool to retrieve information about a specific group by its ID. Use when you need to get details of a GitLab group.3 params
Tool to retrieve information about a specific group by its ID. Use when you need to get details of a GitLab group.
Parameters* required
idintegerThe ID or URL-encoded path of the group.
with_custom_attributesbooleanInclude custom attributes in response (administrators only).
with_projectsbooleanInclude details from projects that belong to the specified group (defaults to true). Deprecated, scheduled for removal in API v5.default: true
GITLAB_GET_GROUP_MEMBERTool to retrieve details for a specific group member. Use when you need to fetch membership information for a user in a group after you know both group ID and user ID.2 params
Tool to retrieve details for a specific group member. Use when you need to fetch membership information for a user in a group after you know both group ID and user ID.
Parameters* required
idintegerThe ID or URL-encoded path of the group.
user_idintegerThe user ID of the group member to retrieve.
GITLAB_GET_GROUPSGet Groups13 params
Get Groups
Parameters* required
all_availablebooleanInclude all groups the user has access to (admin only).
min_access_levelintegerLimit to groups with minimum access level.
order_bystringReturn groups ordered by this field.one of
id · name · path · created_at · updated_atownedbooleanLimit to groups owned by the current user.
pageintegerPage number for pagination.
per_pageintegerNumber of results per page.
searchstringSearch for groups by name or path.
skip_groups[]arrayList of group IDs to exclude.
sortstringReturn groups sorted in 'asc' or 'desc' order.one of
asc · descstatisticsbooleanInclude group statistics (admin only).
with_custom_attributesbooleanInclude custom attributes in response (admins only).
with_projectsbooleanInclude project details in response (deprecated).
with_two_factorbooleanInclude groups requiring two-factor authentication.
GITLAB_GET_JOB_DETAILSTool to retrieve details of a single job by its ID within a specified project. Use this when you need to fetch specific information about a particular CI/CD job.2 params
Tool to retrieve details of a single job by its ID within a specified project. Use this when you need to fetch specific information about a particular CI/CD job.
Parameters* required
job_idintegerThe ID of the job.
project_idintegerThe ID or URL-encoded path of the project.
GITLAB_GET_MERGE_REQUEST_NOTESTool to fetch comments on a merge request. Use when you need to retrieve all notes for a specific merge request.4 params
Tool to fetch comments on a merge request. Use when you need to retrieve all notes for a specific merge request.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
merge_request_iidintegerInternal ID of the merge request.
pageintegerPage number to retrieve.
per_pageintegerNumber of notes per page (max 100).
GITLAB_GET_PROJECTTool to get a single project by ID or URL-encoded path.1 params
Tool to get a single project by ID or URL-encoded path.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
GITLAB_GET_PROJECT_LANGUAGESTool to list programming languages used in a project with percentages. Use when you need the project language breakdown.1 params
Tool to list programming languages used in a project with percentages. Use when you need the project language breakdown.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
GITLAB_GET_PROJECT_MEMBERTool to retrieve details for a specific project member. Use after confirming project and user IDs to fetch membership information for a project member.2 params
Tool to retrieve details for a specific project member. Use after confirming project and user IDs to fetch membership information for a project member.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
user_idintegerThe user ID of the project member to retrieve.
GITLAB_GET_PROJECT_MEMBER_ALLTool to retrieve details for a specific project member (including inherited and invited members). Use when you need the effective membership info (including invitations and inheritance).2 params
Tool to retrieve details for a specific project member (including inherited and invited members). Use when you need the effective membership info (including invitations and inheritance).
Parameters* required
idintegerThe ID or URL-encoded path of the project.
user_idintegerThe user ID of the project member.
GITLAB_GET_PROJECT_MERGE_REQUEST_COMMITSTool to get commits of a merge request. Use when you need to retrieve all commits associated with a specific merge request.2 params
Tool to get commits of a merge request. Use when you need to retrieve all commits associated with a specific merge request.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
merge_request_iidintegerInternal ID of the merge request.
GITLAB_GET_PROJECT_MERGE_REQUESTSTool to retrieve a list of merge requests for a specific project. Use when you need to get all merge requests associated with a project, with options to filter by state, labels, milestones, and other attributes.36 params
Tool to retrieve a list of merge requests for a specific project. Use when you need to get all merge requests associated with a project, with options to filter by state, labels, milestones, and other attributes.
Parameters* required
approvedstringFilters merge requests by their approved status. yes returns only approved merge requests. no returns only non-approved merge requests. Requires the mr_approved_filter feature flag, disabled by def...
approved_by_idsarrayReturns merge requests approved by all the users with the given id, up to 5 users. None returns merge requests with no approvals. Any returns merge requests with an approval. Premium and Ultimate o...
approver_idsarrayReturns merge requests which have specified all the users with the given id as individual approvers. None returns merge requests without approvers. Any returns merge requests with an approver. Prem...
assignee_idintegerReturns merge requests assigned to the given user id. None returns unassigned merge requests. Any returns merge requests with an assignee.
author_idintegerReturns merge requests created by the given user id. Mutually exclusive with author_username. Combine with scope=all or scope=assigned_to_me.
author_usernamestringReturns merge requests created by the given username. Mutually exclusive with author_id.
created_afterstringReturns merge requests created on or after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
created_beforestringReturns merge requests created on or before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
deployed_afterstringReturns merge requests deployed after the given date/time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
deployed_beforestringReturns merge requests deployed before the given date/time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
environmentstringReturns merge requests deployed to the given environment.
idintegerThe ID or URL-encoded path of the project.
iids[]arrayReturns the request having the given iid.
labelsstringReturns merge requests matching a comma-separated list of labels. None lists all merge requests with no labels. Any lists all merge requests with at least one label. Predefined names are case-insen...
merge_user_idintegerReturns the merge requests merged by the user with the given user id. Mutually exclusive with merge_user_username. Introduced in GitLab 17.0.
merge_user_usernamestringReturns the merge requests merged by the user with the given username. Mutually exclusive with merge_user_id. Introduced in GitLab 17.0.
milestonestringReturns merge requests for a specific milestone. None returns merge requests with no milestone. Any returns merge requests that have an assigned milestone.
my_reaction_emojistringReturns merge requests reacted by the authenticated user by the given emoji. None returns issues not given a reaction. Any returns issues given at least one reaction.
not_filterobjectReturns merge requests that do not match the parameters supplied. Accepts: labels, milestone, author_id, author_username, assignee_id, assignee_username, reviewer_id, reviewer_username, my_reaction...
order_bystringReturns requests ordered by created_at, title, merged_at, or updated_at fields. Default is created_at.
+16 more parameters. See the server's own documentation for the full schema.
GITLAB_GET_PROJECTSTool to list all projects accessible to the authenticated user. Supports filtering.19 params
Tool to list all projects accessible to the authenticated user. Supports filtering.
Parameters* required
archivedbooleanLimit by archived status.
id_afterintegerLimit results to projects with IDs greater than the specified ID.
id_beforeintegerLimit results to projects with IDs less than the specified ID.
membershipbooleanLimit by projects that the current user is a member of.
min_access_levelintegerLimit by current user minimal role (access_level).
order_bystringReturn projects ordered by this field. Default is 'created_at'.one of
id · name · path · created_at · updated_at · star_countownedbooleanLimit by projects explicitly owned by the current user.
pageintegerPage number for pagination.
per_pageintegerNumber of items per page (1-100).
searchstringReturn list of projects matching search criteria (case-insensitive substring).
simplebooleanReturn only limited fields for each project.
sortstringReturn projects sorted in 'asc' or 'desc' order. Default is 'desc'.one of
asc · descstarredbooleanLimit by projects starred by the current user.
statisticsbooleanInclude project statistics. Available to Reporter role and above.
visibilitystringLimit by project visibility.one of
private · internal · publicwith_custom_attributesbooleanInclude custom attributes in response (admin only).
with_issues_enabledbooleanLimit by enabled issues feature.
with_merge_requests_enabledbooleanLimit by enabled merge requests feature.
with_programming_languagestringLimit by projects which use the given programming language.
GITLAB_GET_PROJECTS_ID_MERGE_REQUESTS_IID_DIFFSTool to list all diff versions of a merge request. Use when you need to inspect changes across different diff versions after creating or updating a merge request.2 params
Tool to list all diff versions of a merge request. Use when you need to inspect changes across different diff versions after creating or updating a merge request.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
merge_request_iidintegerThe internal ID of the merge request.
GITLAB_GET_REPOSITORY_BRANCHTool to retrieve information about a specific branch in a project. Use when you need to get details for a single branch.2 params
Tool to retrieve information about a specific branch in a project. Use when you need to get details for a single branch.
Parameters* required
branch_namestringThe URL-encoded name of the branch.
project_idintegerThe ID or URL-encoded path of the project.
GITLAB_GET_REPOSITORY_BRANCHESRetrieves a list of repository branches for a project. Use this when you need to get all branches or search for specific branches within a GitLab project.3 params
Retrieves a list of repository branches for a project. Use this when you need to get all branches or search for specific branches within a GitLab project.
Parameters* required
project_idintegerThe ID or URL-encoded path of the project.
regexstringReturn list of branches with names matching a re2 regular expression.
searchstringReturn list of branches containing the search string. Use `^term` to find branches that begin with `term`, and `term$` to find branches that end with `term`.
GITLAB_GET_SINGLE_COMMITTool to get a specific commit identified by the commit hash or name of a branch or tag. Use this when you need to retrieve detailed information about a single commit in a GitLab project repository.3 params
Tool to get a specific commit identified by the commit hash or name of a branch or tag. Use this when you need to retrieve detailed information about a single commit in a GitLab project repository.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
shastringThe commit hash or name of a repository branch or tag.
statsbooleanInclude commit stats. Default is true.default: true
GITLAB_GET_SINGLE_PIPELINETool to retrieve details of a single pipeline by its ID within a specified project. Use when you need to get information about a specific CI/CD pipeline.2 params
Tool to retrieve details of a single pipeline by its ID within a specified project. Use when you need to get information about a specific CI/CD pipeline.
Parameters* required
pipeline_idintegerThe ID of the pipeline.
project_idintegerThe ID or URL-encoded path of the project.
GITLAB_GET_USERTool to retrieve information about a specific user by their ID. Use when you need to fetch details for a single GitLab user.1 params
Tool to retrieve information about a specific user by their ID. Use when you need to fetch details for a single GitLab user.
Parameters* required
idintegerThe ID of the user.
GITLAB_GET_USER_PREFERENCESTool to get the current user's preferences. Use when you need to retrieve the user's diff display and CI identity JWT settings after authentication.
Tool to get the current user's preferences. Use when you need to retrieve the user's diff display and CI identity JWT settings after authentication.
No parameter schema in public metadata yet.
GITLAB_GET_USERSTool to retrieve a list of users from GitLab. Use this when you need to find user information, search for specific users, or filter users based on various criteria like activity status or creation date.24 params
Tool to retrieve a list of users from GitLab. Use this when you need to find user information, search for specific users, or filter users based on various criteria like activity status or creation date.
Parameters* required
activebooleanFilters only active users. Default is false.
adminsbooleanReturn only administrators. Default is false. (Admin only)
auditorsbooleanReturn only auditor users. Default is false. If not included, it returns all users. (Admin only, Premium and Ultimate only)
blockedbooleanFilters only blocked users. Default is false.
created_afterstringReturn users created after specified time (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ).
created_beforestringReturn users created before specified time (ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ).
exclude_activebooleanFilters only non active users. Default is false.
exclude_externalbooleanFilters only non external users. Default is false.
exclude_humansbooleanFilters only bot or internal users. Default is false.
exclude_internalbooleanFilters only non internal users. Default is false.
extern_uidstringGet a single user with a specific external authentication provider UID. (Admin only)
externalbooleanFilters only external users. Default is false.
humansbooleanFilters only regular users that are not bot or internal users. Default is false.
order_bystringReturn users ordered by 'id', 'name', 'username', 'created_at', or 'updated_at' fields. Default is 'id'. (Admin only)one of
id · name · username · created_at · updated_atpageintegerPage number for pagination.
per_pageintegerNumber of items per page for pagination.
providerstringThe external provider. (Admin only)
searchstringSearch for users by name, username, or public email.
skip_ldapbooleanSkip LDAP users. (Admin only, Premium and Ultimate only)
sortstringReturn users sorted in 'asc' or 'desc' order. Default is 'desc'. (Admin only)one of
asc · desc+4 more parameters. See the server's own documentation for the full schema.
GITLAB_GET_USERS_ID_STATUSTool to get a user's status by ID. Use when you need to retrieve a GitLab user's current status message, emoji, and availability after identifying their user ID.1 params
Tool to get a user's status by ID. Use when you need to retrieve a GitLab user's current status message, emoji, and availability after identifying their user ID.
Parameters* required
user_idintegerThe numeric ID of the GitLab user whose status you want to retrieve.
GITLAB_GET_USER_STATUSTool to get the current user's status. Use when displaying or verifying the authenticated user's GitLab status after login.
Tool to get the current user's status. Use when displaying or verifying the authenticated user's GitLab status after login.
No parameter schema in public metadata yet.
GITLAB_GET_USER_SUPPORT_PINTool to get details of the current user's Support PIN. Use when you need to retrieve the active support PIN and its expiration for the authenticated user.
Tool to get details of the current user's Support PIN. Use when you need to retrieve the active support PIN and its expiration for the authenticated user.
No parameter schema in public metadata yet.
GITLAB_IMPORT_PROJECT_MEMBERSTool to import members from one project to another. Use when migrating members between projects.2 params
Tool to import members from one project to another. Use when migrating members between projects.
Parameters* required
idstringID or URL-encoded path of the target project to receive members.
project_idstringID or URL-encoded path of the source project to import members from.
GITLAB_LIST_ALL_GROUP_MEMBERSTool to list all members of a group including direct, inherited, and invited members. Use when you need a comprehensive membership list beyond direct members.3 params
Tool to list all members of a group including direct, inherited, and invited members. Use when you need a comprehensive membership list beyond direct members.
Parameters* required
idintegerThe ID or URL-encoded path of the group.
pageintegerPage number for pagination.
per_pageintegerNumber of items per page for pagination.
GITLAB_LIST_ALL_PROJECT_MEMBERSTool to list all members of a project (direct, inherited, invited). Use when you need the effective membership list including inherited and invited members.7 params
Tool to list all members of a project (direct, inherited, invited). Use when you need the effective membership list including inherited and invited members.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
pageintegerPage number for pagination.
per_pageintegerNumber of items per page for pagination.
querystringFilters results based on a given name, email, or username. Use partial values to widen the scope of the query.
show_seat_infobooleanShow seat information for users.
statestringFilter results by member state, one of 'awaiting' or 'active'. Premium and Ultimate only.one of
awaiting · activeuser_idsarrayFilter the results on the given user IDs.
GITLAB_LIST_BILLABLE_GROUP_MEMBERSTool to list billable members of a top-level group (including its subgroups and projects). Use when generating billing reports; requires Owner role on the group.5 params
Tool to list billable members of a top-level group (including its subgroups and projects). Use when generating billing reports; requires Owner role on the group.
Parameters* required
idintegerThe ID or URL-encoded path of the top-level group. Only top-level groups are supported.
pageintegerPage number for pagination (must be ≥ 1).
per_pageintegerNumber of items per page for pagination (must be ≥ 1).
searchstringSearch string to filter members by name, username, or public email.
sortstringSort order for results. Supported values: access_level_asc|access_level_desc|last_joined|name_asc|name_desc|oldest_joined|oldest_sign_in|recent_sign_in|last_activity_on_asc|last_activity_on_desc.one of
access_level_asc · access_level_desc · last_joined · name_asc · name_desc · oldest_joinedGITLAB_LIST_GROUP_MEMBERSTool to list direct members of a group. Use when you need to retrieve or filter a group's direct membership.10 params
Tool to list direct members of a group. Use when you need to retrieve or filter a group's direct membership.
Parameters* required
activebooleanWhen true, return only active users.
idintegerThe ID or URL-encoded path of the group.
include_inheritedbooleanInclude members inherited from ancestor groups when true.
pageintegerPage number for pagination.
per_pageintegerNumber of results per page (1–100).
querystringFilter members by name, username, or email substring.
relationsarrayMembership relation types to include: direct, descendants, inherited, or shared.
skip_usersarrayList of user IDs to exclude from the results.
sortstringOrder results by access level, ascending or descending.one of
access_level_asc · access_level_desctwo_factorstringFilter users by two-factor authentication status.one of
enabled · disabledGITLAB_LIST_PENDING_GROUP_MEMBERSTool to list pending members of a group and its subgroups and projects. Use when you need to review users awaiting approval or invited without an account. Call after confirming the top-level group ID.3 params
Tool to list pending members of a group and its subgroups and projects. Use when you need to review users awaiting approval or invited without an account. Call after confirming the top-level group ID.
Parameters* required
idintegerThe ID or URL-encoded path of the top-level group.
pageintegerPage number for pagination (1-based index).
per_pageintegerNumber of items per page for pagination (max 100).
GITLAB_LIST_PIPELINE_JOBSTool to retrieve a list of jobs for a specified pipeline within a project. Use this when you need to inspect the status or details of jobs associated with a particular CI/CD pipeline.4 params
Tool to retrieve a list of jobs for a specified pipeline within a project. Use this when you need to inspect the status or details of jobs associated with a particular CI/CD pipeline.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
include_retriedbooleanInclude retried jobs in the response. Defaults to false.default: false
pipeline_idintegerThe ID of the pipeline.
scopestringThe scope of jobs to show. Can be a single status or a list of statuses. If not provided, all jobs are returned.one of
canceled · canceling · created · failed · manual · pendingGITLAB_LIST_PROJECT_GROUPSTool to list ancestor groups of a project. Use when you need to retrieve all groups a project belongs to or is shared with.8 params
Tool to list ancestor groups of a project. Use when you need to retrieve all groups a project belongs to or is shared with.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
pageintegerPage number of the results to retrieve.
per_pageintegerNumber of items to return per page.
searchstringSearch for specific groups by name.
shared_min_access_levelintegerLimit to shared groups with at least this access level.
shared_visible_onlybooleanLimit to shared groups user has access to.
skip_groupsarraySkip the group IDs passed.
with_sharedbooleanInclude projects shared with this group. Default is false.
GITLAB_LIST_PROJECT_INVITED_GROUPSTool to list groups invited to a project. Use when auditing which groups have access to a project.3 params
Tool to list groups invited to a project. Use when auditing which groups have access to a project.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
pageintegerPage number for pagination.
per_pageintegerNumber of items to return per page.
GITLAB_LIST_PROJECT_PIPELINESTool to retrieve a list of pipelines for a specified project. Use when you need to get information about CI/CD pipelines, such as their status, source, or creation/update times.17 params
Tool to retrieve a list of pipelines for a specified project. Use when you need to get information about CI/CD pipelines, such as their status, source, or creation/update times.
Parameters* required
created_afterstringReturn pipelines created after the specified date (ISO 8601 format).
created_beforestringReturn pipelines created before the specified date (ISO 8601 format).
idintegerThe ID or URL-encoded path of the project.
namestringReturn pipelines with the specified name.
order_bystringOrder pipelines by 'id', 'status', 'ref', 'updated_at' or 'user_id'.one of
id · status · ref · updated_at · user_iddefault: idpageintegerPage number for pagination.
per_pageintegerNumber of items per page for pagination.
refstringThe ref of pipelines.
scopestringThe scope of pipelines, one of: 'running', 'pending', 'finished', 'branches', 'tags'.one of
running · pending · finished · branches · tagsshastringThe SHA of pipelines.
sortstringSort pipelines in 'asc' or 'desc' order.one of
asc · descdefault: descsourcestringThe pipeline source. To return child pipelines, set to 'parent_pipeline'.
statusstringThe status of pipelines.one of
created · waiting_for_resource · preparing · pending · running · successupdated_afterstringReturn pipelines updated after the specified date (ISO 8601 format).
updated_beforestringReturn pipelines updated before the specified date (ISO 8601 format).
usernamestringThe username of the user who triggered pipelines.
yaml_errorsbooleanReturns pipelines with invalid configurations.
GITLAB_LIST_PROJECT_SHAREABLE_GROUPSTool to list groups that can be shared with a project. Use before sharing a project to fetch eligible groups.5 params
Tool to list groups that can be shared with a project. Use before sharing a project to fetch eligible groups.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
pageintegerPage number for pagination.
per_pageintegerNumber of items per page for pagination.
searchstringSearch term to filter groups by name or path.
skip_groupsarrayList of group IDs to exclude from the results.
GITLAB_LIST_PROJECT_TAGSTool to retrieve a list of repository tags for a specified project. Use when you need to get all tags associated with a project in GitLab.6 params
Tool to retrieve a list of repository tags for a specified project. Use when you need to get all tags associated with a project in GitLab.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
order_bystringReturn tags ordered by `name`, `updated`, or `version`. Default is `updated`.
pageintegerPage number of the results to retrieve.
per_pageintegerNumber of items to return per page.
searchstringReturn a list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term`.
sortstringReturn tags sorted in `asc` or `desc` order. Default is `desc`.
GITLAB_LIST_PROJECT_TRANSFER_LOCATIONSTool to list namespaces available for project transfer. Use when you need to determine which groups a project can be transferred into.2 params
Tool to list namespaces available for project transfer. Use when you need to determine which groups a project can be transferred into.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
searchstringThe group names to search for.
GITLAB_LIST_PROJECT_USERSTool to list users of a project. Use after you have a project ID and want to retrieve its users.3 params
Tool to list users of a project. Use after you have a project ID and want to retrieve its users.
Parameters* required
idstringThe ID or URL-encoded path of the project.
searchstringFilter users by name or username.
skip_usersarrayList of user IDs to exclude from the result.
GITLAB_LIST_REPOSITORY_COMMITSTool to get a list of repository commits in a project. Use when you need to retrieve commit history for a specific project, branch, or time range.11 params
Tool to get a list of repository commits in a project. Use when you need to retrieve commit history for a specific project, branch, or time range.
Parameters* required
allbooleanRetrieve every commit from the repository. When set to true, the ref_name parameter is ignored.
authorstringSearch commits by commit author.
first_parentbooleanFollow only the first parent commit upon seeing a merge commit.
orderstringList commits in order. Possible values: default, topo. Defaults to default, the commits are shown in reverse chronological order.one of
default · topopathstringThe file path to filter commits by.
project_idintegerThe ID or URL-encoded path of the project.
ref_namestringThe name of a repository branch, tag or revision range, or if not given the default branch.
sincestringOnly commits after or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
trailersbooleanParse and include Git trailers for every commit.
untilstringOnly commits before or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
with_statsbooleanStats about each commit are added to the response.
GITLAB_LIST_USER_PROJECTSTool to list projects owned by a specific user. Use after obtaining target user identity to fetch owned projects.22 params
Tool to list projects owned by a specific user. Use after obtaining target user identity to fetch owned projects.
Parameters* required
archivedbooleanLimit by archived status.
idintegerThe ID or username of the user whose projects to list.
id_afterintegerLimit results to projects with IDs greater than the specified ID.
id_beforeintegerLimit results to projects with IDs less than the specified ID.
membershipbooleanLimit by projects that the current user is a member of.
min_access_levelintegerLimit by current user minimal role (access_level).
order_bystringReturn projects ordered by this field. Default is 'created_at'.one of
id · name · path · created_at · updated_at · star_countownedbooleanLimit by projects explicitly owned by the specified user.
pageintegerPage number for pagination.
per_pageintegerNumber of items per page (1-100).
searchstringReturn list of projects matching search criteria (case-insensitive substring).
simplebooleanReturn only limited fields for each project.
sortstringReturn projects sorted in asc or desc order. Default is 'desc'.one of
asc · descstarredbooleanLimit by projects starred by the specified user.
statisticsbooleanInclude project statistics. Available to Reporter role and above.
updated_afterstringLimit projects updated after given time (ISO 8601).
updated_beforestringLimit projects updated before given time (ISO 8601).
visibilitystringLimit by project visibility.one of
private · internal · publicwith_custom_attributesbooleanInclude custom attributes in response (admin only).
with_issues_enabledbooleanLimit by enabled issues feature.
+2 more parameters. See the server's own documentation for the full schema.
GITLAB_POST_USER_SUPPORT_PINTool to create a support PIN for your authenticated user. Use when GitLab Support requests a PIN to verify your identity.
Tool to create a support PIN for your authenticated user. Use when GitLab Support requests a PIN to verify your identity.
No parameter schema in public metadata yet.
GITLAB_PUT_USER_PREFERENCESTool to update the current user's preferences. Use when adjusting default diff viewing and CI identity settings.3 params
Tool to update the current user's preferences. Use when adjusting default diff viewing and CI identity settings.
Parameters* required
pass_user_identities_to_ci_jwtbooleanFlag indicating the user passes their external identities as CI information. Internal use only; do not expose to third-party services.
show_whitespace_in_diffsbooleanFlag indicating the user sees whitespace changes in diffs.
view_diffs_file_by_filebooleanFlag indicating the user sees only one file diff per page.
GITLAB_SET_USER_STATUSTool to set the current user's status. Use when you need to update availability or convey current mood on GitLab.3 params
Tool to set the current user's status. Use when you need to update availability or convey current mood on GitLab.
Parameters* required
clear_status_afterstringAutomatically clear status after the specified time interval. Allowed values: 30_minutes, 3_hours, 8_hours, 1_day, 3_days, 7_days, 30_days.one of
30_minutes · 3_hours · 8_hours · 1_day · 3_days · 7_daysemojistringName of the emoji to use as status. Defaults to 'speech_balloon' if omitted.
messagestringStatus message to display. Max 100 characters; can contain emoji codes.
GITLAB_SHARE_PROJECT_WITH_GROUPTool to share a project with a group. Use when you need to grant a group specific access level to a project.4 params
Tool to share a project with a group. Use when you need to grant a group specific access level to a project.
Parameters* required
expires_atstringExpiration date for the group share in YYYY-MM-DD format (ISO 8601).
group_accessintegerThe access level to grant the group. One of GitLab's access levels, e.g., 30 for Developer, 40 for Maintainer.
group_idintegerThe ID of the group to share with.
idintegerThe ID or URL-encoded path of the project.
GITLAB_START_PROJECT_HOUSEKEEPINGTool to start the housekeeping task for a project. Use when you need to trigger manual maintenance or pruning on a repository.2 params
Tool to start the housekeeping task for a project. Use when you need to trigger manual maintenance or pruning on a repository.
Parameters* required
idintegerThe ID or URL-encoded path of the project.
taskstringType of housekeeping task to perform. `prune` triggers a manual prune of unreachable objects; `eager` triggers eager housekeeping.one of
prune · eager
GitLab MCP Server
Connect your AI assistant to GitLab so it can review merge requests, triage pipelines, manage issues, and draft releases — in plain language. One static binary (or a container), 1000+ GitLab tools over the full REST + GraphQL API, working with Claude, Cursor, VS Code, and any MCP client.
You talk to your AI assistant; it does the GitLab work. No project IDs, API endpoints, or JSON to remember.
"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"
🤖 Using an AI assistant? Give it this repository URL and ask it to install the server for your client. Everything a model needs to do it headlessly — the declarative per-client config,
claude mcp addone-liners, and defaults — is inllms.txt(no interactive wizard required).
Install in 60 seconds
Pick one. Each path ends with you typing a prompt to your assistant.
Want to look before installing? The browser inspector signs in with OAuth and calls the hosted endpoint read-only from a browser tab — nothing downloaded. Running it yourself is still the way to keep using it.
One-click install
| Client | One-click button | Token step |
|---|---|---|
| VS Code |  |
prompts you (masked) |
| VS Code Insiders |  |
prompts you (masked) |
| Cursor |  |
edit YOUR_GITLAB_TOKEN |
| LM Studio |  |
edit YOUR_GITLAB_TOKEN |
| Kiro |  |
edit YOUR_GITLAB_TOKEN |
| Claude Desktop |  |
settings UI (keychain) |
Each button registers the Docker-based server (auto-pulls the image on first run; you need Docker installed). The Claude Desktop row instead downloads a native .mcpb desktop extension (macOS universal + Windows, no Docker) — open it with Claude Desktop and fill in the settings. Need a token? Create a Personal Access Token with the api scope. Self-managed GitLab? Add a GITLAB_URL env var in your client's MCP config after install.
Claude Code (claude mcp add)
Docker (no install — pulls the image on first run):
claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx --transport stdio \
-- docker run -i --rm -e GITLAB_TOKEN ghcr.io/jmrplens/gitlab-mcp-server:latest --http=false
Or install the native binary first, then register it:
# Any platform (npm/pnpm) — downloads only your platform's prebuilt binary
npx -y @jmrp.io/gitlab-mcp-server # zero install; clients launch it directly
npm install -g @jmrp.io/gitlab-mcp-server # or install globally (npm)
pnpm add -g @jmrp.io/gitlab-mcp-server # or globally (pnpm)
# macOS/Linux (Homebrew)
brew install jmrplens/tap/gitlab-mcp-server
# Linux/macOS (script)
curl -fsSL https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.sh | sh
# Windows (winget)
winget install --id jmrplens.gitlab-mcp-server -e
# Windows (PowerShell)
irm https://raw.githubusercontent.com/jmrplens/gitlab-mcp-server/main/scripts/install.ps1 | iex
claude mcp add gitlab --env GITLAB_TOKEN=glpat-xxxx -- gitlab-mcp-server
Clients that launch servers with npx need no install at all — point them at
npx -y @jmrp.io/gitlab-mcp-server.
Self-managed GitLab? Add --env GITLAB_URL=https://gitlab.example.com (and --env GITLAB_SKIP_TLS_VERIFY=true for self-signed certs).
Guided setup (any client, no flags to remember)
The binary ships a setup wizard that collects your GitLab token and configures your MCP client for you — ideal if you'd rather not edit JSON:
gitlab-mcp-server --setup
It auto-detects VS Code, Claude Desktop, Claude Code, Cursor, and Windsurf and writes the right config. On Windows, double-click the .exe to launch it.
Manual JSON (Claude Desktop, Cursor, VS Code, …)
Show JSON config for native binary and Docker
Native binary (Claude Desktop mcpServers, Cursor, etc.):
{
"mcpServers": {
"gitlab": {
"command": "/path/to/gitlab-mcp-server",
"env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
}
}
}
VS Code (.vscode/mcp.json, note servers + type):
{
"servers": {
"gitlab": {
"type": "stdio",
"command": "/path/to/gitlab-mcp-server",
"env": { "GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx" }
}
}
}
Docker variant — replace "command"/"args" with:
"command": "docker",
"args": ["run", "-i", "--rm", "-e", "GITLAB_TOKEN", "ghcr.io/jmrplens/gitlab-mcp-server:latest", "--http=false"]
Cline (VS Code) — open the Cline sidebar → MCP servers icon → Edit Global MCP, or edit the settings file directly:
- macOS:
~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - Linux:
~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json - Windows:
%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Cline uses the mcpServers shape shown above for the native binary.
For a shared, long-running HTTP deployment instead of per-user stdio, see HTTP Server Mode.
Try it without installing anything (hosted endpoint)
A public instance runs at https://mcp.jmrp.io/gitlab — nothing to install, no account beyond your own GitLab token. Point any HTTP-capable MCP client at it:
{
"mcpServers": {
"gitlab": {
"type": "http",
"url": "https://mcp.jmrp.io/gitlab",
"headers": { "Authorization": "Bearer glpat-xxxxxxxxxxxx" }
}
}
}
The endpoint runs in OAuth mode, so the credential travels as Authorization: Bearer — a GitLab personal access token works there, verified exactly like an OAuth one, which is what keeps clients with no OAuth flow (and headless use) working. It travels per request and is never stored on the server. A client that speaks the OAuth flow needs no header at all: the 401 carries an RFC 9728 challenge it follows to authorize in the browser. PRIVATE-TOKEN is the legacy-mode header and is not accepted here; the instance is fixed to https://gitlab.com, so GITLAB-URL is ignored.
A read_api token is accepted and served a read-only tool surface — the write check is per action, so a credential that cannot break anything is a supported way to use the endpoint rather than a rejected one.
Two pages make it easier still. The server card lists the whole catalog with no credential at all and carries copy-paste config for Claude Code, Cursor and VS Code — including the OAuth client ID those clients need. The browser inspector calls the same endpoint read-only from a browser tab: sign in with OAuth, pick a tool, read the raw JSON-RPC it returns — nothing installed.
It is the fastest way to try the server, and the right way to keep using it is still locally (any option above) — for one concrete reason, not as a disclaimer: your token and every request pass through someone else's machine. Running it locally means your credentials and your GitLab traffic never leave your computer, which also makes it the only sensible option for a private self-managed instance.
The endpoint is stateless streamable HTTP on the default dynamic surface: POST is the transport and an authenticated GET answers 405 by design; with no credential, any method answers 401 carrying the RFC 6750 challenge an OAuth client follows — a bare curl that gets 401 is the endpoint working, not failing. https://mcp.jmrp.io/gitlab/health needs no credential and answers 200 with {"status":"ok",…}. A self-hosted HTTP deployment can also run --auth-mode=oauth --gitlab-url=https://gitlab.com --public-url=https://mcp.example.com/mcp (both are required: OAuth needs a fixed instance, and --public-url is the RFC 9728 resource identifier — pass exactly the URL your clients are configured with, since a client discards metadata naming a different one), where clients discover GitLab as the authorization server through that metadata and authorize in the browser instead of copying tokens — see OAuth App Setup. It is one of the servers listed at mcp.jmrp.io, a directory of the MCP servers I maintain, each reachable at its own endpoint; https://mcp.jmrp.io/servers.json is the same list for automated clients.
It is a personal service, run by one person and offered as-is: no SLA, no support channel, and no promise it is unchanged next week. It adds no quota of its own — every call spends GitLab.com's own limits, under your own token. And it tracks the latest release automatically, so what it serves follows the newest tag rather than a pinned version.
Then just ask: open your AI client and try "List my GitLab projects." See the Getting Started guide for per-client details and more example prompts.
Why this server
- Plain-language GitLab. The AI translates "is MR !15 safe to merge?" into the right API calls. You don't touch endpoints, IDs, or JSON.
- The whole platform — 1000+ tools. Broad GitLab REST v4 + GraphQL coverage: projects, branches, tags, releases, merge requests, issues, pipelines, jobs, groups, users, wikis, environments, deployments, packages, container registry, runners, feature flags, CI/CD variables, security, admin, tokens, and more.
- Low-token by default. The default dynamic surface exposes just 2 tools (
find+execute) while reaching the full catalog — so it fits any client's context window. (Token footprint →) - Proven with real models. An automated evaluator runs Anthropic, Google, OpenAI, and Qwen against live GitLab instances: 99.5% aggregate success across thousands of operations. (Results →)
- Safe by design. Read-only mode, safe mode (dry-run preview of every mutation), TLS options for self-hosted GitLab, and continuous SonarCloud quality/security gates.
- Runs anywhere. One static binary or container; Windows, Linux & macOS; amd64 & arm64; stdio (desktop) and HTTP (remote).
More: resources, prompts, and capabilities
- 45 MCP resources (read-only data: projects, issues, pipelines, MRs, branches, members, the surface-aware
gitlab://toolsmanifest, and workflow best-practice guides). 26 single-object kinds are also subscribable. - 37 MCP prompts (code review, pipeline status, risk assessment, release notes, standup, analytics, audit, and more).
- 4 elicitation wizards (interactive issue/MR/release/project creation).
- 4 MCP capabilities (completions, progress, elicitation, and resource subscriptions — live
resources/updatednotifications, honored by polling) and 51 tool icons (50 domain icons plus the project mark) for visual identification in MCP clients. - Pagination on every list endpoint with full metadata.
Tool surfaces
The server can present GitLab in three shapes, controlled by TOOL_SURFACE. The default needs no configuration.
| Surface | Visible tools | Best for |
|---|---|---|
| Dynamic (default) | 2 (gitlab_find_action, gitlab_execute_action) | Lowest token cost; reaches the full catalog via find/execute. |
Meta-tools (meta) | 32 base / 49 Ultimate / 50 GitLab.com Ultimate | Domain-grouped dispatchers with an action parameter. |
Individual (individual) | ~847 Free/CE · ~999 Premium · 1065–1071 Ultimate | One MCP tool per GitLab operation; needs a large context window. |
Tool counts scale with your GitLab edition (GITLAB_TIER); higher tiers expose more actions. See Dynamic Toolset and Meta-Tools Reference for the ranking model, safety guards, and full catalogs. For dynamic runs where resources dominate context, set CAPABILITY_SURFACE=minimal.
Token Footprint
Measured with go run ./cmd/audit_tokens/ -footprint against the current catalog. Totals estimate startup context visible to an MCP client: visible tool schemas plus shared resources and prompts, using the cl100k_base tokenizer (GPT-4/GPT-3.5 encoding). For the full matrix (meta and individual surfaces, all META_PARAM_SCHEMA modes), see Token Footprint Reference.
Default configuration: with TOOL_SURFACE unset or TOOL_SURFACE=dynamic, CAPABILITY_SURFACE=full, META_TOOLS unset, META_PARAM_SCHEMA=opaque, and GITLAB_TIER unset (detected, fallback free), the server uses the dynamic find/execute surface. Use TOOL_SURFACE=meta only when you explicitly want domain meta-tools; use TOOL_SURFACE=individual only when your client can handle the full tool catalog.
Configuration (TOOL_SURFACE / CAPABILITY_SURFACE) | Tier | Visible tools | Reachable actions | META_PARAM_SCHEMA | Tool schema tokens | Shared tokens | Total tokens |
|---|---|---|---|---|---|---|---|
dynamic / full (default) | Free/CE | 2 | 851 | n/a | 1,499 | 8,720 | 10,219 |
dynamic / minimal | Free/CE | 2 | 851 | n/a | 1,499 | 170 | 1,669 |
dynamic / full (default) | Premium | 2 | 1,003 | n/a | 1,499 | 8,720 | 10,219 |
dynamic / minimal | Premium | 2 | 1,003 | n/a | 1,499 | 170 | 1,669 |
dynamic / full (default) | Ultimate | 2 | 1,069 | n/a | 1,499 | 8,720 | 10,219 |
dynamic / minimal | Ultimate | 2 | 1,069 | n/a | 1,499 | 170 | 1,669 |
Rows use the base Community Edition catalog unless the Tier column says otherwise. GITLAB_TIER controls which actions are available; higher tiers expose more tools and thus more reachable actions.
Compatibility
| MCP Capability | Support |
|---|---|
| Tools | Up to 1071 individual / 32–50 meta |
| Resources | 45 (static + templates) |
| Prompts | 37 templates |
| Completions | 17 argument types: projects, groups, users, branches, tags, MRs, issues, pipelines, jobs, labels, milestones, SHAs |
| Server logs | Structured (text/JSON) to stderr — not the MCP logging capability, which is deprecated (SEP-2577) and deliberately not advertised |
| Progress | Tool execution progress reporting |
| Elicitation | 4 interactive creation wizards |
| Subscriptions | resources/updated by polling, 26 resource kinds |
Tested with: VS Code + GitHub Copilot, Claude Desktop, Claude Code, Cursor, Windsurf, JetBrains IDEs, Zed, Kiro, Cline. See the full Compatibility Matrix.
AI Model Tool-Use Evaluation
The project includes an automated evaluator for model-facing MCP quality. It runs schema-only checks against the tool catalog or executes validated model tool calls through MCP against Docker GitLab CE or licensed Enterprise instances populated with fixtures. It measures whether each model chooses the correct action, sends valid parameters, recovers from actionable GitLab errors, and respects destructive-action safeguards — across Anthropic, Google, OpenAI, and Qwen.
Current published result: Docker CE dynamic 20260627-232303.
| Provider | Model | Compatibility | Tool accuracy | Recovery | Docker live status |
|---|---|---|---|---|---|
| Anthropic | claude-haiku-4-5-20251001 | OK | 100.0% | 100.0% (2/2) | 100.0% final across 555 ops |
gemini-flash-latest | OK | 100.0% | 100.0% (4/4) | 100.0% final across 555 ops | |
| OpenAI | gpt-5.4-nano | Review | 99.3% | 84.6% (11/13) | 98.0% final across 555 ops |
| Qwen | qwen3.6-flash | OK | 100.0% | 100.0% (5/5) | 100.0% final across 555 ops |
The published model-evaluation set covers 596 task attempts and 2220 expected MCP operations. Across the selected reports, models emitted 2265 tool calls over 2265 model requests, with 99.5% aggregate final success. See AI Model Evaluation Results for the detailed current matrix.
Enterprise meta & dynamic evaluation results
Current published result: Docker Enterprise meta 20260527.
| Provider | Model | Compatibility | Tool accuracy | Recovery | Docker live status |
|---|---|---|---|---|---|
| Anthropic | claude-haiku-4-5-20251001 | OK | 100.0% | 100.0% (1/1) | 100.0% final across 84 ops |
gemini-flash-latest | Review | 78.2% | 100.0% (7/7) | 100.0% final across 84 ops | |
| OpenAI | gpt-5.4-nano | Review | 100.0% | 100.0% (4/4) | 100.0% final across 84 ops |
| Qwen | qwen3.6-flash | OK | 100.0% | 100.0% (1/1) | 100.0% final across 84 ops |
The published model-evaluation set covers 92 task attempts and 336 expected MCP operations. Across the selected reports, models emitted 345 tool calls over 350 model requests, with 100.0% aggregate final success. See AI Model Evaluation Results for the detailed current matrix.
Current published result: Docker Enterprise dynamic 20260628-015421.
| Provider | Model | Compatibility | Tool accuracy | Recovery | Docker live status |
|---|---|---|---|---|---|
| Anthropic | claude-haiku-4-5-20251001 | OK | 100.0% | 100.0% (1/1) | 100.0% final across 202 ops |
gemini-flash-latest | OK | 100.0% | 100.0% (2/2) | 100.0% final across 202 ops | |
| OpenAI | gpt-5.4-nano | OK | 100.0% | No repairs | 100.0% final across 202 ops |
| Qwen | qwen3.6-flash | OK | 100.0% | 100.0% (1/1) | 100.0% final across 202 ops |
The published model-evaluation set covers 124 task attempts and 808 expected MCP operations. Across the selected reports, models emitted 817 tool calls over 817 model requests, with 100.0% aggregate final success. See AI Model Evaluation Results for the detailed current matrix.
Documentation
Full documentation is at jmrp.io/docs/gitlab-mcp-server. Use this map for the source-of-truth reference on a specific area:
| Document | Description |
|---|---|
| Getting Started | Download, setup wizard, per-client configuration |
| IDE Configuration | Per-client stdio, HTTP legacy, and HTTP OAuth examples |
| Configuration | Environment variables, transport modes, TLS |
| Environment Variables | Exhaustive environment variable table with defaults and examples |
| CLI Reference | All command-line flags, exit codes, and runtime examples |
| HTTP Server Mode | Shared HTTP deployments, authentication, server pool isolation |
| OAuth App Setup | GitLab OAuth application, scopes, redirect URIs, and which clients can complete a flow |
| CI/CD | Running the server inside GitLab CI and GitHub Actions pipelines |
| Output Format | The response contract every tool follows: content blocks, pagination, next steps |
| Error Handling | Error classification, GitLab message extraction, and the hints tools return |
| Tools Reference | All individual tools with input/output schemas, including GitLab.com-only Orbit |
| Meta-Tools | 32/49/50 domain meta-tools with action dispatching |
| Dynamic Toolset | 2-tool low-token mode with canonical action catalog, safety model, and examples |
| Resources | All 45 resources with URI templates |
| Prompts | All 37 prompts with arguments and output format |
| Auto-Update | Self-update mechanism, modes, and release format |
| Testing | Unit, E2E, schema model evaluation, Docker model evaluation, and curated model results |
| Security | Security model, token scopes, input validation |
| Architecture | System architecture, component design, data flow |
| Development Guide | Building, testing, CI/CD, contributing |
| Troubleshooting | Common startup, token, TLS, transport, and tool-discovery issues |
FAQ
Does it work with self-hosted GitLab?
Yes. Set GITLAB_URL to your instance URL. When GITLAB_URL is omitted, stdio mode uses https://gitlab.com. Self-signed TLS certificates are supported via GITLAB_SKIP_TLS_VERIFY=true.
Is my data safe?
When you run it yourself — locally over stdio, or on your own infrastructure over HTTP — all API calls go directly to your GitLab instance. The one request that leaves for anywhere else is the update check against GitHub Releases, which is on by default and disabled with AUTO_UPDATE=false.
The exception is the hosted endpoint: using https://mcp.jmrp.io/gitlab means your token and every request pass through that machine. Nothing is stored there, but it is someone else's server, which is why the hosted section says to keep using it locally.
See PRIVACY.md for exactly what the update check sends, and SECURITY.md for the security model.
Can I use it in read-only mode?
Yes. Set GITLAB_READ_ONLY=true to disable all mutating tools (create, update, delete). Only read operations will be available.
Alternatively, set GITLAB_SAFE_MODE=true for a dry-run mode: mutating tools remain visible but return a structured JSON preview instead of executing. Useful for auditing, training, or reviewing what an AI assistant would do.
What GitLab editions are supported?
Both Community Edition (CE) and Enterprise Edition (EE). Set GITLAB_TIER=premium or GITLAB_TIER=ultimate in stdio mode to enable additional tools for Premium/Ultimate features (DORA metrics, vulnerabilities, compliance, etc.); leave it unset to detect the tier from the instance license (fallback free). In HTTP mode, --tier can force the tier, otherwise it is detected per token+URL pool entry from the license.
How does it handle rate limiting?
The server includes retry logic with backoff for GitLab API rate limits. Errors are classified as transient (retryable) or permanent, with actionable hints in error messages.
Which AI clients are supported?
Any MCP-compatible client: VS Code + GitHub Copilot, Claude Desktop, Cursor, Claude Code, Windsurf, JetBrains IDEs, Zed, Kiro, and others. The built-in setup wizard can auto-configure most clients.
Building from Source
git clone https://github.com/jmrplens/gitlab-mcp-server.git
cd gitlab-mcp-server
make build
The published container image is ghcr.io/jmrplens/gitlab-mcp-server:latest. See the Development Guide for cross-compilation, Docker Compose, and contributing guidelines.
| Component | Technology |
|---|---|
| Language | Go 1.27+ |
| MCP SDK | github.com/modelcontextprotocol/go-sdk v1.7.0 |
| GitLab Client | gitlab.com/gitlab-org/api/client-go/v2 v2.59.0 |
| Transport | stdio (default), HTTP (Streamable HTTP) |
Privacy Policy
The server runs entirely on your machine and has no telemetry, analytics, or backend of its own — data flows only between your MCP client and the GitLab instance you configure (plus an optional signed-binary update check against GitHub Releases). Your token is used solely to authenticate GitLab requests and is never logged. Full details: PRIVACY.md.
Contributing & Security
- Contributing: see CONTRIBUTING.md for development guidelines, branch naming, commit conventions, and the PR process.
- Security: see SECURITY.md for the security policy and vulnerability reporting.
- Code of Conduct: see CODE_OF_CONDUCT.md (Contributor Covenant v2.1).
Repository mirror: GitHub is the canonical repository. A read-only mirror is available on GitLab.com for discoverability; please open contributions on GitHub.
Unnecessary statistics — numbers nobody asked for
File counts
| Category | Files | Lines |
|---|---|---|
Source (.go, non-test) | 996 | 204,792 |
Unit tests (_test.go) | 554 | 317,234 |
| End-to-end tests | 183 | 49,160 |
| Total | 1,733 | 571,186 |
Functions
| Category | Count |
|---|---|
| Source functions | 7,780 |
| — exported (public) | 2,693 |
| — unexported (private) | 5,087 |
Unit test functions (TestXxx) | 12,037 |
Subtests (t.Run(...)) | 3,048 |
| End-to-end test functions | 466 |
Ratios worth noting
| Observation | Value |
|---|---|
| Test lines vs source lines | 1.55× more tests than code |
| Average source file length | ~205 lines |
| Average test file length | ~572 lines |
| Comment lines in source | 24,735 (~12.1% of source) |
| Test functions per source function | 1.5× |
Code patterns
| Pattern | Count |
|---|---|
if err != nil checks | 6,773 |
defer statements | 966 |
struct types defined | 2,750 |
//nolint suppressions | 268 |
TODO / FIXME / HACK comments | 2 |
Project
| Metric | Value |
|---|---|
| Go packages | 238 |
Direct dependencies (go.mod) | 18 |
| Indirect dependencies | 46 |
Hall of fame
| Record | File |
|---|---|
| Longest source file | internal/tools/dynamic/register.go — 3,851 lines |
| Longest test file | internal/tools/projects/projects_test.go — 8,183 lines |
Because why not
| Fact | Value |
|---|---|
| Source code printed at 55 lines/page | ~3,723 pages of A4 |
Source lines mentioning "gitlab" | 12,808 (impossible to avoid) |
| Longest function name in source | assertDynamicCompatibilityPolicyOwnedByActionCompat (51 chars) |
| Longest test function name | TestRequiredMissingAndUnknownParamNames_SchemaValidation_ReturnsSortedMissingAndUnknown (87 chars) |
Maintained by José M. Requena Plens · Project page · Hosted instance: mcp.jmrp.io/gitlab
Featured
Plug Mailtrap into your AI workflow and let it handle the email.
Connect Mailtrap MCP →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →Make coding agent sessions - Searchable, Shareable, Vendor-neutral & Scored.
Try For Free →Your agent targets a perfect 10 Code Health score. Deterministic. Every commit.
Try For Free →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →belt cli automatically finds the best tools and skills for your agent. image, video, music, tts...
one prompt install →Configuration
GITLAB_URLdefault: https://gitlab.comGitLab instance URL (default: https://gitlab.com; set for self-managed instances)
GITLAB_TOKEN*secretGitLab Personal Access Token (glpat-...)
GITLAB_SKIP_TLS_VERIFYdefault: falseSkip TLS certificate verification for self-signed certs (default: false)
TOOL_SURFACEdefault: dynamicTool catalog selector: dynamic, meta, or individual (default: dynamic)
CAPABILITY_SURFACEdefault: fullResource and prompt catalog selector: full or minimal (default: full)
META_PARAM_SCHEMAdefault: opaqueMeta-tool input schema detail: opaque, compact, or full (default: opaque)
GITLAB_ENTERPRISEdefault: falseEnable GitLab Premium/Ultimate tools; GitLab.com Enterprise/Premium also exposes Orbit Knowledge Graph tools (default: false)
GITLAB_READ_ONLYdefault: falseRead-only mode: disables all mutating tools (default: false)
GITLAB_SAFE_MODEdefault: falseSafe mode: intercepts mutating tools and returns a JSON preview instead of executing (default: false)
EMBEDDED_RESOURCESdefault: trueAppend EmbeddedResource content blocks (clickable links to MCP resources) to get_* tool results (default: true)
EXCLUDE_TOOLSComma-separated tool names to exclude from registration (e.g. gitlab_admin,gitlab_runner)
GITLAB_IGNORE_SCOPESdefault: falseSkip Personal Access Token scope detection and register all tools regardless of token permissions (default: false)
UPLOAD_MAX_FILE_SIZEdefault: 2147483648Maximum attachment upload size in bytes or human-readable (e.g. 2GB). Default: 2147483648 (2 GB)
GITLAB_MCP_ALLOWED_IMPORT_DIRSExtra OS path-list-separated directories allowed for local GitLab import archives
RATE_LIMIT_RPSdefault: 0Per-server tools/call rate limit in requests per second; 0 disables it (default: 0)
RATE_LIMIT_BURSTdefault: 40Token-bucket burst size when RATE_LIMIT_RPS is greater than 0 (default: 40)
LOG_LEVELdefault: infoLogging verbosity (default: info)
AUTO_UPDATEdefault: trueAuto-update mode: true (auto-apply), check (log-only), false (disabled). Default: true
AUTO_UPDATE_REPOdefault: jmrplens/gitlab-mcp-serverGitHub repository slug for release assets (default: jmrplens/gitlab-mcp-server)
AUTO_UPDATE_INTERVALdefault: 1hPeriodic update check interval in HTTP mode (default: 1h)
AUTO_UPDATE_TIMEOUTdefault: 60sStartup/background update timeout, range 5s-10m (default: 60s)
Categories
Registryactive
Packagehttps://github.com/jmrplens/gitlab-mcp-server/releases/download/v2.1.3/gitlab-mcp-server-linux-amd64
TransportSTDIO, HTTP
AuthRequired
UpdatedJun 6, 2026
