Summary
A comprehensive GitLab API wrapper that exposes 84 tools covering the full development lifecycle. You get project management, merge request workflows with inline code review and multi-line discussion threads, CI/CD pipeline control, approval rule configuration at both project and MR level, and CI/CD variable management for projects and groups. Supports both GitLab.com and self-hosted instances without requiring GitLab Duo or Premium tiers. Works in read-only mode if you want to lock down write operations. Built on FastMCP with clean Pydantic models. Particularly useful for teams managing complex approval workflows or automating pipeline operations across multiple projects, since it handles everything from creating commits with file actions to sequencing merge operations and retrying failed jobs.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
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
namestringThe name of the group.
pathstringThe path of the group.
avatarstringImage file for avatar of the group.
parent_idintegerThe parent group ID for creating nested group.
visibilitystringThe group’s visibility.one of
private · internal · publicdescriptionstringThe group’s description.
lfs_enabledbooleanEnable/disable Large File Storage (LFS) for the projects in this group.
default_branchstringThe default branch name for group’s projects.
emails_enabledbooleanEnable email notifications.
membership_lockbooleanUsers cannot be added to projects in this group. Premium and Ultimate only.
organization_idintegerThe organization ID for the group.
duo_availabilitystringDuo availability setting. Note: In the UI, never_on is displayed as "Always Off".one of
default_on · default_off · never_onmentions_disabledbooleanDisable the capability of a group from getting mentioned.
wiki_access_levelstringThe wiki access level. Premium and Ultimate only.one of
disabled · private · enabledauto_devops_enabledbooleanDefault to Auto DevOps pipeline for all projects within this group.
share_with_group_lockbooleanPrevent sharing a project with another group within this 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.
subgroup_creation_levelstringAllowed to create subgroups.one of
owner · maintainertwo_factor_grace_periodintegerTime before Two-factor authentication is enforced (in hours).
enabled_git_access_protocolstringEnabled protocols for Git access.one of
ssh · http · allexperiment_features_enabledbooleanEnable experiment features for this group.
shared_runners_minutes_limitintegerCan be set by administrators only. Maximum number of monthly compute minutes for this group. Can be nil (default; inherit system default), 0 (unlimited), or > 0. GitLab Self-Managed, Premium and Ultimate only.
require_two_factor_authenticationbooleanRequire all users in this group to set up two-factor authentication.
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": False}
extra_shared_runners_minutes_limitintegerCan be set by administrators only. Additional compute minutes for this group. GitLab Self-Managed, Premium and Ultimate only.
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
namestringThe name of the project.
pathstringThe path or URL-friendly name for the project.
visibilitystringProject visibility.one of
private · internal · publicdescriptionstringProject description.
namespace_idintegerThe namespace (group or user ID) under which to create the project.
wiki_enabledbooleanEnable wiki feature.
default_branchstringThe default branch name.
issues_enabledbooleanEnable issues feature.
snippets_enabledbooleanEnable snippets feature.
build_git_strategystringGit strategy for builds.
merge_requests_enabledbooleanEnable merge requests feature.
container_registry_enabledbooleanEnable container registry.
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
idstringThe global ID or URL-encoded path of the project.
iidintegerThe internal ID of the project’s issue (requires administrator or project owner rights).
titlestringThe title of an issue.
labelsstringComma-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.
weightintegerThe weight of the issue. Valid values are greater than or equal to 0. Premium and Ultimate only.
epic_idintegerID of the epic to add the issue to. Valid values are greater than or equal to 0. Premium and Ultimate only.
due_datestringThe due date. Date time string in the format `YYYY-MM-DD`, for example `2016-03-11`.
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.
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.
issue_typestringThe type of issue. One of `issue`, `incident`, `test_case` or `task`. Default is `issue`.one of
issue · incident · test_case · taskdefault: issueassignee_idintegerThe ID of the user to assign the issue to. Only appears on GitLab Free.
descriptionstringThe description of an issue. Limited to 1,048,576 characters.
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
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.
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`.
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 values take precedence over the default values.
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
refstringThe branch name or commit SHA to create the new branch from.
project_idintegerThe ID or URL-encoded path of the project.
branch_namestringThe name of the new branch.
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
idintegerThe ID or URL-encoded path of the project to be deleted.
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 15.11).
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.11).
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
shastringThe commit hash.
ref_typestringThe scope of commits to list. Possible values are `branch`, `tag`, or `all`.one of
branch · tag · alldefault: allproject_idintegerThe ID or URL-encoded path of the project.
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
shastringThe commit hash.
project_idintegerThe ID or URL-encoded path of the project.
first_parentbooleanFollow only the first parent commit upon seeing a merge commit.
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_projectsbooleanInclude details from projects that belong to the specified group (defaults to true). Deprecated, scheduled for removal in API v5.default: true
with_custom_attributesbooleanInclude custom attributes in response (administrators only).
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
pageintegerPage number for pagination.
sortstringReturn groups sorted in 'asc' or 'desc' order.one of
asc · descownedbooleanLimit to groups owned by the current user.
searchstringSearch for groups by name or path.
order_bystringReturn groups ordered by this field.one of
id · name · path · created_at · updated_atper_pageintegerNumber of results per page.
statisticsbooleanInclude group statistics (admin only).
all_availablebooleanInclude all groups the user has access to (admin only).
skip_groups[]arrayList of group IDs to exclude.
with_projectsbooleanInclude project details in response (deprecated).
with_two_factorbooleanInclude groups requiring two-factor authentication.
min_access_levelintegerLimit to groups with minimum access level.
with_custom_attributesbooleanInclude custom attributes in response (admins only).
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.
pageintegerPage number to retrieve.
per_pageintegerNumber of notes per page (max 100).
merge_request_iidintegerInternal ID of the merge request.
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
idintegerThe ID or URL-encoded path of the project.
wipstringFilter merge requests against their wip status. Use yes to return only draft merge requests, no to return non-draft merge requests.
pageintegerThe page of results to return. Defaults to 1.
sortstringReturns requests sorted in asc or desc order. Default is desc.
viewstringIf simple, returns the iid, URL, title, description, and basic state of merge request.
scopestringReturns merge requests for the given scope: created_by_me, assigned_to_me or all. Defaults to created_by_me.
statestringReturns all merge requests or just those that are opened, closed, locked, or merged.
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-insensitive.
searchstringSearch merge requests against their title and description.
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 default.
order_bystringReturns requests ordered by created_at, title, merged_at, or updated_at fields. Default is created_at.
per_pageintegerThe number of results per page. Defaults to 20.
author_idintegerReturns merge requests created by the given user id. Mutually exclusive with author_username. Combine with scope=all or scope=assigned_to_me.
milestonestringReturns merge requests for a specific milestone. None returns merge requests with no milestone. Any returns merge requests that have an assigned milestone.
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_emoji.
assignee_idintegerReturns merge requests assigned to the given user id. None returns unassigned merge requests. Any returns merge requests with an assignee.
environmentstringReturns merge requests deployed to the given environment.
reviewer_idintegerReturns merge requests which have the user as a reviewer with the given user id. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_username.
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. Premium and Ultimate only.
created_afterstringReturns merge requests created on or after the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
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.
source_branchstringReturns merge requests with the given source branch.
target_branchstringReturns merge requests with the given target branch.
updated_afterstringReturns merge requests updated 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).
updated_beforestringReturns merge requests updated on or before the given time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
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 only.
author_usernamestringReturns merge requests created by the given username. Mutually exclusive with author_id.
deployed_beforestringReturns merge requests deployed before the given date/time. Expected in ISO 8601 format (2019-03-15T08:00:00Z).
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.
reviewer_usernamestringReturns merge requests which have the user as a reviewer with the given username. None returns merge requests with no reviewers. Any returns merge requests with any reviewer. Mutually exclusive with reviewer_id.
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.
with_labels_detailsbooleanIf true, response returns more details for each label in labels field: :name, :color, :description, :description_html, :text_color. Default is false.
with_merge_status_recheckbooleanIf true, this projection requests (but does not guarantee) an asynchronous recalculation of the merge_status field. Enable the restrict_merge_status_recheck feature flag to ignore this attribute when requested by users without at least the Developer role.
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
pageintegerPage number for pagination.
sortstringReturn projects sorted in 'asc' or 'desc' order. Default is 'desc'.one of
asc · descownedbooleanLimit by projects explicitly owned by the current user.
searchstringReturn list of projects matching search criteria (case-insensitive substring).
simplebooleanReturn only limited fields for each project.
starredbooleanLimit by projects starred by the current user.
archivedbooleanLimit by archived status.
id_afterintegerLimit results to projects with IDs greater than the specified ID.
order_bystringReturn projects ordered by this field. Default is 'created_at'.one of
id · name · path · created_at · updated_at · star_countper_pageintegerNumber of items per page (1-100).
id_beforeintegerLimit results to projects with IDs less than the specified ID.
membershipbooleanLimit by projects that the current user is a member of.
statisticsbooleanInclude project statistics. Available to Reporter role and above.
visibilitystringLimit by project visibility.one of
private · internal · publicmin_access_levelintegerLimit by current user minimal role (access_level).
with_issues_enabledbooleanLimit by enabled issues feature.
with_custom_attributesbooleanInclude custom attributes in response (admin only).
with_programming_languagestringLimit by projects which use the given programming language.
with_merge_requests_enabledbooleanLimit by enabled merge requests feature.
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
project_idintegerThe ID or URL-encoded path of the project.
branch_namestringThe URL-encoded name of the branch.
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
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`.
project_idintegerThe ID or URL-encoded path of the project.
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
project_idintegerThe ID or URL-encoded path of the project.
pipeline_idintegerThe ID of the pipeline.
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
pageintegerPage number for pagination.
sortstringReturn users sorted in 'asc' or 'desc' order. Default is 'desc'. (Admin only)one of
asc · descactivebooleanFilters only active users. Default is false.
adminsbooleanReturn only administrators. Default is false. (Admin only)
humansbooleanFilters only regular users that are not bot or internal users. Default is false.
searchstringSearch for users by name, username, or public email.
blockedbooleanFilters only blocked users. Default is false.
auditorsbooleanReturn only auditor users. Default is false. If not included, it returns all users. (Admin only, Premium and Ultimate only)
externalbooleanFilters only external 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_atper_pageintegerNumber of items per page for pagination.
providerstringThe external provider. (Admin only)
usernamestringGet a single user with a specific username.
skip_ldapbooleanSkip LDAP users. (Admin only, Premium and Ultimate only)
extern_uidstringGet a single user with a specific external authentication provider UID. (Admin only)
two_factorstringFilter users by Two-factor authentication. Filter values are 'enabled' or 'disabled'. (Admin only)one of
enabled · disabledcreated_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_humansbooleanFilters only bot or internal users. Default is false.
exclude_externalbooleanFilters only non external users. Default is false.
exclude_internalbooleanFilters only non internal users. Default is false.
without_projectsbooleanFilter users without projects. Default is false. (Admin only)
without_project_botsbooleanFilters user without project bots. Default is false.
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.
querystringFilters results based on a given name, email, or username. Use partial values to widen the scope of the query.
statestringFilter results by member state, one of 'awaiting' or 'active'. Premium and Ultimate only.one of
awaiting · activeper_pageintegerNumber of items per page for pagination.
user_idsarrayFilter the results on the given user IDs.
show_seat_infobooleanShow seat information for users.
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).
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_joinedsearchstringSearch string to filter members by name, username, or public email.
per_pageintegerNumber of items per page for pagination (must be ≥ 1).
GITLAB_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
idintegerThe ID or URL-encoded path of the group.
pageintegerPage number for pagination.
sortstringOrder results by access level, ascending or descending.one of
access_level_asc · access_level_descquerystringFilter members by name, username, or email substring.
activebooleanWhen true, return only active users.
per_pageintegerNumber of results per page (1–100).
relationsarrayMembership relation types to include: direct, descendants, inherited, or shared.
skip_usersarrayList of user IDs to exclude from the results.
two_factorstringFilter users by two-factor authentication status.one of
enabled · disabledinclude_inheritedbooleanInclude members inherited from ancestor groups when true.
GITLAB_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.
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 · pendingpipeline_idintegerThe ID of the pipeline.
include_retriedbooleanInclude retried jobs in the response. Defaults to false.default: false
GITLAB_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.
searchstringSearch for specific groups by name.
per_pageintegerNumber of items to return per page.
skip_groupsarraySkip the group IDs passed.
with_sharedbooleanInclude projects shared with this group. Default is false.
shared_visible_onlybooleanLimit to shared groups user has access to.
shared_min_access_levelintegerLimit to shared groups with at least this access level.
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
idintegerThe ID or URL-encoded path of the project.
refstringThe ref of pipelines.
shastringThe SHA of pipelines.
namestringReturn pipelines with the specified name.
pageintegerPage number for pagination.
sortstringSort pipelines in 'asc' or 'desc' order.one of
asc · descdefault: descscopestringThe scope of pipelines, one of: 'running', 'pending', 'finished', 'branches', 'tags'.one of
running · pending · finished · branches · tagssourcestringThe pipeline source. To return child pipelines, set to 'parent_pipeline'.
statusstringThe status of pipelines.one of
created · waiting_for_resource · preparing · pending · running · successorder_bystringOrder pipelines by 'id', 'status', 'ref', 'updated_at' or 'user_id'.one of
id · status · ref · updated_at · user_iddefault: idper_pageintegerNumber of items per page for pagination.
usernamestringThe username of the user who triggered pipelines.
yaml_errorsbooleanReturns pipelines with invalid configurations.
created_afterstringReturn pipelines created after the specified date (ISO 8601 format).
updated_afterstringReturn pipelines updated after the specified date (ISO 8601 format).
created_beforestringReturn pipelines created before the specified date (ISO 8601 format).
updated_beforestringReturn pipelines updated before the specified date (ISO 8601 format).
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.
searchstringSearch term to filter groups by name or path.
per_pageintegerNumber of items per page for pagination.
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.
pageintegerPage number of the results to retrieve.
sortstringReturn tags sorted in `asc` or `desc` order. Default is `desc`.
searchstringReturn a list of tags matching the search criteria. You can use `^term` and `term$` to find tags that begin and end with `term`.
order_bystringReturn tags ordered by `name`, `updated`, or `version`. Default is `updated`.
per_pageintegerNumber of items to return per page.
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.
pathstringThe file path to filter commits by.
orderstringList commits in order. Possible values: default, topo. Defaults to default, the commits are shown in reverse chronological order.one of
default · toposincestringOnly commits after or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
untilstringOnly commits before or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
authorstringSearch commits by commit author.
ref_namestringThe name of a repository branch, tag or revision range, or if not given the default branch.
trailersbooleanParse and include Git trailers for every commit.
project_idintegerThe ID or URL-encoded path of the project.
with_statsbooleanStats about each commit are added to the response.
first_parentbooleanFollow only the first parent commit upon seeing a merge commit.
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
idintegerThe ID or username of the user whose projects to list.
pageintegerPage number for pagination.
sortstringReturn projects sorted in asc or desc order. Default is 'desc'.one of
asc · descownedbooleanLimit by projects explicitly owned by the specified user.
searchstringReturn list of projects matching search criteria (case-insensitive substring).
simplebooleanReturn only limited fields for each project.
starredbooleanLimit by projects starred by the specified user.
archivedbooleanLimit by archived status.
id_afterintegerLimit results to projects with IDs greater than the specified ID.
order_bystringReturn projects ordered by this field. Default is 'created_at'.one of
id · name · path · created_at · updated_at · star_countper_pageintegerNumber of items per page (1-100).
id_beforeintegerLimit results to projects with IDs less than the specified ID.
membershipbooleanLimit by projects that the current user is a member of.
statisticsbooleanInclude project statistics. Available to Reporter role and above.
visibilitystringLimit by project visibility.one of
private · internal · publicupdated_afterstringLimit projects updated after given time (ISO 8601).
updated_beforestringLimit projects updated before given time (ISO 8601).
min_access_levelintegerLimit by current user minimal role (access_level).
with_issues_enabledbooleanLimit by enabled issues feature.
with_custom_attributesbooleanInclude custom attributes in response (admin only).
with_programming_languagestringLimit by projects which use the given programming language.
with_merge_requests_enabledbooleanLimit by enabled merge requests feature.
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
view_diffs_file_by_filebooleanFlag indicating the user sees only one file diff per page.
show_whitespace_in_diffsbooleanFlag indicating the user sees whitespace changes in diffs.
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.
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
emojistringName of the emoji to use as status. Defaults to 'speech_balloon' if omitted.
messagestringStatus message to display. Max 100 characters; can contain emoji codes.
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_daysGITLAB_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
idintegerThe ID or URL-encoded path of the project.
group_idintegerThe ID of the group to share with.
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.
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 · eagermcp-gitlab
mcp-gitlab is a Model Context Protocol (MCP) server for the GitLab REST API that provides 83 tools, 7 resources, and 6 prompts for AI assistants to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, code reviews, and more. Works with Claude Desktop, Claude Code, Cursor, Windsurf, VS Code Copilot, and any MCP-compatible client.
Supports GitLab.com and self-hosted GitLab instances (CE/EE). No GitLab Duo or Premium required.
Built with FastMCP, httpx, and Pydantic.
Install: uvx mcp-gitlab | PyPI | MCP Registry | Changelog
1-Click Installation
💡 Tip: For other AI assistants (Claude Code, Windsurf, IntelliJ, Gemini CLI), visit the GitLab MCP Installation Gateway.
Manual Setup Guides (Click to expand)
Prerequisite: Install
uvfirst (required for alluvxinstall flows). Install uv.
Claude Code
claude mcp add gitlab -- uvx mcp-gitlab
Windsurf & IntelliJ
Windsurf: Add to ~/.codeium/windsurf/mcp_config.json
IntelliJ: Add to Settings | Tools | MCP Servers
Note: The actual server config starts at
gitlabinside themcpServersobject.
{
"mcpServers": {
"gitlab": {
"command": "uvx",
"args": ["mcp-gitlab"],
"env": {
"GITLAB_URL": "https://gitlab.example.com",
"GITLAB_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx"
}
}
}
}
Gemini CLI
gemini mcp add -e GITLAB_URL=https://gitlab.example.com -e GITLAB_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx gitlab uvx mcp-gitlab
pip / uv
uv pip install mcp-gitlab
Configuration
| Variable | Required | Default | Description |
|---|---|---|---|
GITLAB_URL | Yes | - | GitLab instance URL (e.g. https://gitlab.example.com) |
GITLAB_TOKEN | Yes | - | Authentication token (see below) |
GITLAB_READ_ONLY | No | false | Set to true to disable write operations |
GITLAB_TIMEOUT | No | 30 | Request timeout in seconds |
GITLAB_SSL_VERIFY | No | true | Set to false to skip SSL verification |
Supported Token Types
The server checks these environment variables in order — first match wins:
GITLAB_TOKENGITLAB_PATGITLAB_PERSONAL_ACCESS_TOKENGITLAB_API_TOKEN
These accept any of the following token types:
| Token Type | Format | Use Case |
|---|---|---|
| Personal access token | glpat-xxx | User-level access with api scope |
| OAuth2 token | oauth-xxx | OAuth app integrations |
| CI job token | $CI_JOB_TOKEN | GitLab CI pipeline access |
Compatibility
| Client | Supported | Install Method |
|---|---|---|
| Claude Desktop | Yes | claude_desktop_config.json |
| Claude Code | Yes | claude mcp add |
| Cursor | Yes | One-click deeplink or .cursor/mcp.json |
| VS Code Copilot | Yes | One-click deeplink or .vscode/mcp.json |
| Windsurf | Yes | ~/.codeium/windsurf/mcp_config.json |
| Any MCP client | Yes | stdio or HTTP transport |
Tools (83)
| Category | Count | Tools |
|---|---|---|
| Projects | 4 | get, create, delete, update merge settings |
| Project Approvals | 10 | get/update config, CRUD approval rules (project + MR) |
| Groups | 6 | list, get, share/unshare project, share/unshare group |
| Branches | 3 | list, create, delete |
| Commits | 4 | list, get (with diff), create, compare |
| Merge Requests | 16 | list, get, create, update, merge, merge-sequence, rebase, changes, approve, unapprove, get approvals, list reviewers, list pipelines, list commits, subscribe, unsubscribe |
| MR Notes | 6 | list, add, delete, update, award emoji, remove emoji |
| MR Discussions | 4 | list, create (inline + multi-line), reply, resolve |
| Pipelines | 5 | list, get (with jobs), create, retry, cancel |
| Jobs | 4 | retry, play, cancel, get log |
| Tags | 4 | list, get, create, delete |
| Releases | 5 | list, get, create, update, delete |
| CI/CD Variables | 8 | CRUD for project variables, CRUD for group variables |
| Issues | 5 | list, get, create, update, add comment |
Full tool reference (click to expand)
Projects
| Tool | Description |
|---|---|
gitlab_get_project | Get project details |
gitlab_create_project | Create a new project |
gitlab_delete_project | Delete a project |
gitlab_update_project_merge_settings | Update merge settings |
Project Approvals
| Tool | Description |
|---|---|
gitlab_get_project_approvals | Get approval config |
gitlab_update_project_approvals | Update approval settings |
gitlab_list_project_approval_rules | List approval rules |
gitlab_create_project_approval_rule | Create approval rule |
gitlab_update_project_approval_rule | Update approval rule |
gitlab_delete_project_approval_rule | Delete approval rule |
gitlab_list_mr_approval_rules | List MR approval rules |
gitlab_create_mr_approval_rule | Create MR approval rule |
gitlab_update_mr_approval_rule | Update MR approval rule |
gitlab_delete_mr_approval_rule | Delete MR approval rule |
Groups
| Tool | Description |
|---|---|
gitlab_list_groups | List groups |
gitlab_get_group | Get group details |
gitlab_share_project_with_group | Share project with group |
gitlab_unshare_project_with_group | Unshare project from group |
gitlab_share_group_with_group | Share group with group |
gitlab_unshare_group_with_group | Unshare group from group |
Branches
| Tool | Description |
|---|---|
gitlab_list_branches | List branches |
gitlab_create_branch | Create a branch |
gitlab_delete_branch | Delete a branch |
Commits
| Tool | Description |
|---|---|
gitlab_list_commits | List commits |
gitlab_get_commit | Get commit (with optional diff) |
gitlab_create_commit | Create commit with file actions |
gitlab_compare | Compare branches/tags/commits |
Merge Requests
| Tool | Description |
|---|---|
gitlab_list_mrs | List merge requests |
gitlab_get_mr | Get MR details |
gitlab_create_mr | Create merge request |
gitlab_update_mr | Update merge request |
gitlab_merge_mr | Merge a merge request |
gitlab_merge_mr_sequence | Merge multiple MRs in order |
gitlab_rebase_mr | Rebase a merge request |
gitlab_mr_changes | Get MR file changes |
gitlab_approve_mr | Approve a merge request |
gitlab_unapprove_mr | Remove approval from a merge request |
gitlab_get_mr_approvals | Get MR approval state |
gitlab_list_mr_pipelines | List MR pipelines |
gitlab_list_mr_commits | List MR commits |
gitlab_subscribe_mr | Subscribe to MR notifications |
gitlab_unsubscribe_mr | Unsubscribe from MR notifications |
MR Notes
| Tool | Description |
|---|---|
gitlab_list_mr_notes | List MR comments |
gitlab_add_mr_note | Add comment to MR |
gitlab_delete_mr_note | Delete MR comment |
gitlab_update_mr_note | Update MR comment |
gitlab_award_emoji | Award emoji to note |
gitlab_remove_emoji | Remove emoji from note |
MR Discussions
| Tool | Description |
|---|---|
gitlab_list_mr_discussions | List discussions |
gitlab_create_mr_discussion | Create discussion (inline + multi-line) |
gitlab_reply_to_discussion | Reply to discussion |
gitlab_resolve_discussion | Resolve/unresolve discussion |
Pipelines
| Tool | Description |
|---|---|
gitlab_list_pipelines | List pipelines |
gitlab_get_pipeline | Get pipeline (with optional jobs) |
gitlab_create_pipeline | Trigger pipeline |
gitlab_retry_pipeline | Retry failed jobs |
gitlab_cancel_pipeline | Cancel pipeline |
Jobs
| Tool | Description |
|---|---|
gitlab_retry_job | Retry a job |
gitlab_play_job | Trigger manual job |
gitlab_cancel_job | Cancel a job |
gitlab_get_job_log | Get job log output |
Tags
| Tool | Description |
|---|---|
gitlab_list_tags | List tags |
gitlab_get_tag | Get tag details |
gitlab_create_tag | Create a tag |
gitlab_delete_tag | Delete a tag |
Releases
| Tool | Description |
|---|---|
gitlab_list_releases | List releases |
gitlab_get_release | Get release details |
gitlab_create_release | Create a release |
gitlab_update_release | Update a release |
gitlab_delete_release | Delete a release |
CI/CD Variables
| Tool | Description |
|---|---|
gitlab_list_variables | List project variables |
gitlab_create_variable | Create project variable |
gitlab_update_variable | Update project variable |
gitlab_delete_variable | Delete project variable |
gitlab_list_group_variables | List group variables |
gitlab_create_group_variable | Create group variable |
gitlab_update_group_variable | Update group variable |
gitlab_delete_group_variable | Delete group variable |
Issues
| Tool | Description |
|---|---|
gitlab_list_issues | List issues |
gitlab_get_issue | Get issue details |
gitlab_create_issue | Create an issue |
gitlab_update_issue | Update an issue |
gitlab_add_issue_comment | Add comment to issue |
Resources (7)
The server exposes curated workflow guides as MCP resources that clients can read on demand.
| URI | Name | Description |
|---|---|---|
resource://rules/gitlab-ci | GitLab CI/CD Pipeline Patterns | Stage design, job rules, caching, artifacts, needs DAG, multi-project pipelines |
resource://rules/git-workflow | Git Workflow Standards | Branch naming, trunk-based flow, merge vs rebase, protected branches |
resource://rules/mr-hygiene | Merge Request Best Practices | MR size, description templates, review checklists, thread resolution |
resource://rules/conventional-commits | Conventional Commits Spec | Commit types, scopes, breaking changes, changelog generation |
resource://guides/code-review | Code Review Standards | Review priorities, inline comments, approval workflows, nit vs blocker |
resource://guides/codeowners | GitLab CODEOWNERS Reference | Syntax, section owners, approval rules, pattern matching |
resource://guides/approval-workflow | Approval Workflow Guide | Approval types, project vs MR-level rules, SHA safety, merge readiness |
Prompts (6)
The server provides MCP prompts — reusable multi-tool workflow templates that clients can surface as slash commands.
| Prompt | Parameters | Workflow |
|---|---|---|
review_mr | project_id, mr_iid | Fetch MR → check pipeline → review changes → write discussion notes |
approve_mr | project_id, mr_iid | Check approvals → verify pipeline → review changes → approve or request changes |
diagnose_pipeline | project_id, pipeline_id | Fetch pipeline → identify failed jobs → get logs → suggest fix |
prepare_release | project_id, tag_name, ref | Compare commits since last tag → draft changelog → create tag + release |
setup_branch_protection | project_id | Review settings → configure merge method → set approval rules |
triage_issues | project_id, label | List open issues → categorize → prioritize → identify duplicates |
Usage Examples
Projects & Branches
"Get details for project my-org/api-gateway"
→ gitlab_get_project(project_id="my-org/api-gateway")
"Create a feature branch from main"
→ gitlab_create_branch(project_id="123", branch_name="feat/login", ref="main")
"Delete all branches merged into main"
→ gitlab_list_branches(project_id="123") → filter merged → gitlab_delete_branch for each
Merge Requests & Code Review
"Open a merge request from feat/login to main"
→ gitlab_create_mr(project_id="123", source_branch="feat/login", target_branch="main", title="Add login")
"Review MR !42 — list changes and add inline comments"
→ gitlab_mr_changes(project_id="123", mr_iid=42)
→ gitlab_create_mr_discussion(project_id="123", mr_iid=42, body="nit: ...", new_path="src/auth.py", new_line=15)
"Merge MR !42 after resolving all threads"
→ gitlab_list_mr_discussions(project_id="123", mr_iid=42) → resolve unresolved
→ gitlab_merge_mr(project_id="123", mr_iid=42, squash=True)
Pipelines & CI/CD
"Show failed pipelines on main this week"
→ gitlab_list_pipelines(project_id="123", ref="main", status="failed")
"Retry a failed pipeline"
→ gitlab_retry_pipeline(project_id="123", pipeline_id=456)
"Get the build log for job 789"
→ gitlab_get_job_log(project_id="123", job_id=789, tail_lines=100)
Issues
"Create a bug report in project 123"
→ gitlab_create_issue(project_id="123", title="Login page 500 error", labels=["bug","P1"])
"Find open issues assigned to me"
→ gitlab_list_issues(project_id="123", state="opened", assignee_username="johndoe")
Security Considerations
- Token scope: Use the minimum required scope.
apiscope grants full access; preferread_apifor read-only deployments. - Read-only mode: Set
GITLAB_READ_ONLY=trueto disable all write operations (create, update, delete, merge). Read-only mode is enforced server-side before any API call. - SSL verification:
GITLAB_SSL_VERIFY=trueby default. Only disable for self-signed certificates in trusted networks. - CI/CD variable masking:
gitlab_list_variablesandgitlab_list_group_variablesautomatically mask values of variables marked as masked in GitLab, returning***MASKED***instead of the actual value. - MCP tool annotations: Each tool declares
readOnlyHint,destructiveHint, andidempotentHintfor client-side permission prompts. - No credential storage: The server does not persist tokens. Credentials are read from environment variables at startup.
Rate Limits & Permissions
Rate Limits
GitLab enforces per-user rate limits (default: 2000 requests/minute for authenticated users). When rate-limited, tools return a 429 error with a hint to wait before retrying. Paginated endpoints default to 20 results per page; use per_page (max 100) to reduce the number of API calls.
Required Permissions
| Operation | Minimum GitLab Role |
|---|---|
| Read projects, MRs, pipelines, issues | Reporter |
| Create branches, MRs, issues | Developer |
| Merge MRs, manage CI/CD variables | Maintainer |
| Delete projects, manage approval rules | Maintainer/Owner |
| Share projects/groups | Owner (or Admin) |
CLI & Transport Options
# Default: stdio transport (for MCP clients)
uvx mcp-gitlab
# HTTP transport (SSE or streamable-http)
uvx mcp-gitlab --transport sse --host 127.0.0.1 --port 8000
uvx mcp-gitlab --transport streamable-http --port 9000
# CLI overrides for config
uvx mcp-gitlab --gitlab-url https://gitlab.example.com --gitlab-token glpat-xxx --read-only
The server loads .env files from the working directory automatically via python-dotenv.
Related MCP Servers
- mcp-atlassian-extended — Jira + Confluence integration (23 tools, 15 resources, 5 prompts)
- mcp-coda — Coda.io integration (54 tools, 12 resources, 5 prompts)
Development
git clone https://github.com/vish288/mcp-gitlab.git
cd mcp-gitlab
uv sync --all-extras
uv run pytest --cov
uv run ruff check .
uv run ruff format --check .
License
MIT
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
GITLAB_TOKEN*secretGitLab personal access token (also accepts GITLAB_PAT or GITLAB_API_TOKEN)
GITLAB_URL*GitLab instance URL (e.g. https://gitlab.com)
GITLAB_READ_ONLYRestrict to read-only operations (true/false)
Categories
Registryactive
Packagemcp-gitlab
TransportSTDIO
AuthRequired
UpdatedMar 5, 2026
