GitLab MCP server tools

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated
Status: Beta

To provide feedback on this feature, leave a comment on issue 561564.

The GitLab MCP server provides a set of tools that integrate with your existing GitLab workflows. You can use these tools to interact directly with GitLab and perform common GitLab operations.

`get_mcp_server_version`

Returns the current version of the GitLab MCP server.

Example:

What version of the GitLab MCP server am I connected to?

`create_issue`

Creates a new issue in a GitLab project.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`title`	string	Yes	Title of the issue.
`description`	string	No	Description of the issue.
`assignee_ids`	array of integers	No	Array of IDs of assigned users.
`milestone_id`	integer	No	ID of the milestone.
`labels`	array of strings	No	Array of label names.
`confidential`	boolean	No	Sets the issue to confidential. Default is `false`.
`epic_id`	integer	No	ID of the linked epic.

Example:

Create a new issue titled "Fix login bug" in project 123 with description
"Users cannot log in with special characters in password"

`get_issue`

Retrieves detailed information about a specific GitLab issue.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`issue_iid`	integer	Yes	Internal ID of the issue.

Example:

Get details for issue 42 in project 123

`create_merge_request`

Creates a merge request in a GitLab project.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`title`	string	Yes	Title of the merge request.
`source_branch`	string	Yes	Name of the source branch.
`target_branch`	string	Yes	Name of the target branch.
`target_project_id`	integer	No	ID of the target project.
`assignee_ids`	array of integers	No	Array of IDs of merge request assignees. Set to `0` or an empty value to unassign all assignees.
`reviewer_ids`	array of integers	No	Array of IDs of merge request reviewers. Set to `0` or an empty value to unassign all reviewers.
`description`	string	No	Description of the merge request.
`labels`	array of strings	No	Array of label names. Set to an empty string to unassign all labels.
`milestone_id`	integer	No	ID of the milestone.

Example:

Create a merge request in project gitlab-org/gitlab titled "Bug fix broken specs"
from branch "fix/specs-broken" into "master" and enable squash

`get_merge_request`

Retrieves a merge request and, optionally, its diffs, commits, notes, pipelines, or discussions. Only the base merge request is returned unless you request associated data with the include parameter.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL of the merge request. Provide this, or `project_id` and `merge_request_iid`.
`project_id`	string	No	ID or URL-encoded path of the project. Required if `url` is missing.
`merge_request_iid`	integer	No	Internal ID of the merge request. Required if `url` is missing.
`include`	array	No	Associated facets to return with the merge request. One of `diffs`, `commits`, `notes`, `pipelines`, or `discussions`. Limited to one facet per call.
`notes_after`	string	No	Cursor for forward pagination of notes. Applies only when `include` is `["notes"]`.
`notes_first`	integer	No	Number of notes to return after the cursor, up to 100. Applies only when `include` is `["notes"]`.

The diffs facet returns change statistics only: overall totals and per-file additions and deletions. To get patch text, use get_merge_request_diffs.

Example:

Get merge request 15 in project gitlab-org/gitlab with its commits

`list_duo_sessions`

Lists your GitLab Duo Agent Platform sessions, excluding Duo Chat sessions. Each session includes its individual status, goal preview, flow definition, and creation timestamp. Project sessions also include a session URL. The goal preview might be truncated.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL of the project to filter sessions by. Do not use with `project_id`.
`project_id`	string	No	Numeric ID or full path of the project to filter sessions by. Do not use with `url`.
`status_group`	string	No	Session status group. One of `active`, `paused`, `awaiting_input`, `completed`, `failed`, or `canceled`.
`after`	string	No	Cursor for forward pagination.
`first`	integer	No	Number of sessions to return for forward pagination. Default is 20, maximum is 100.

The status_group filter can return sessions with multiple individual statuses. Each call returns a single page of results. If more pages exist, the response includes pageInfo.endCursor that you can pass as after.

Example:

List my active Duo Agent Platform sessions in gitlab-org/gitlab

`list_merge_requests`

Lists or searches merge requests in a GitLab project, returning compact merge request metadata.

Parameter	Type	Required	Description
`url`	string	No	URL of the project. Provide exactly one of `url` or `project_id`.
`project_id`	string	No	ID or full path of the project. Provide exactly one of `url` or `project_id`.
`author_username`	string	No	Filter by the username of the merge request author.
`assignee_username`	string	No	Filter by the username of an assignee.
`reviewer_username`	string	No	Filter by the username of a reviewer.
`state`	string	No	Filter by state. One of `opened`, `closed`, `merged`, `locked`, or `all`. Omit to include any state.
`scope`	string	No	Filter relative to the authenticated user. One of `created_by_me`, `assigned_to_me`, or `review_requested`. An explicit username wins for that field.
`milestone`	string	No	Filter by the title of the milestone.
`labels`	string	No	Comma-separated list of label names. Only merge requests with all of these labels are returned.
`search`	string	No	Search query matched against merge request title and description.
`after`	string	No	Cursor for forward pagination.
`first`	integer	No	Number of merge requests to return for forward pagination. Default is 20, maximum is 100.

To retrieve a single merge request in full detail, use get_merge_request. Its diffs, commits, and notes are available from get_merge_request_diffs, get_merge_request_commits, and get_merge_request_notes. For full-text search across resource types, use search.

Example:

List my open merge requests in gitlab-org/gitlab

`get_merge_request_commits`

Retrieves the list of commits in a specific GitLab merge request.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`merge_request_iid`	integer	Yes	Internal ID of the merge request.
`per_page`	integer	No	Number of commits per page.
`page`	integer	No	Current page number.

Example:

Show me all commits in merge request 42 from project 123

`get_merge_request_diffs`

Retrieves the diffs for a specific GitLab merge request.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`merge_request_iid`	integer	Yes	Internal ID of the merge request.
`per_page`	integer	No	Number of diffs per page.
`page`	integer	No	Current page number.

Example:

What files were changed in merge request 25 in the gitlab project?

`get_merge_request_pipelines`

Retrieves the pipelines for a specific GitLab merge request.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`merge_request_iid`	integer	Yes	Internal ID of the merge request.

Example:

Show me all pipelines for merge request 42 in project gitlab-org/gitlab

`create_merge_request_note`

Adds a comment or reply to a discussion on a GitLab merge request as the authenticated user.

Parameter	Type	Required	Description
`url`	string	No	URL of the GitLab merge request. Required if `project_id` and `merge_request_iid` are missing.
`project_id`	string	No	ID or URL-encoded path of the project. Required if `url` is missing.
`merge_request_iid`	integer	No	Internal ID of the merge request. Required if `url` is missing.
`body`	string	Yes	Content of the note. Lines cannot start with `/` to avoid triggering quick actions (for example, `/merge`).
`discussion_id`	string	No	Global ID of the discussion to reply to (in the format `gid://gitlab/Discussion/<id>`). If missing, creates a new top-level note.

Example:

Reply "Thanks, fixed in the latest push" to merge request 42 in project gitlab-org/gitlab

`get_merge_request_notes`

Retrieves the notes (comments and system notes) for a specific GitLab merge request.

Parameter	Type	Required	Description
`url`	string	No	URL of the GitLab merge request. Required if `project_id` and `merge_request_iid` are missing.
`project_id`	string	No	ID or URL-encoded path of the project. Required if `url` is missing.
`merge_request_iid`	integer	No	Internal ID of the merge request. Required if `url` is missing.
`after`	string	No	Cursor for forward pagination.
`before`	string	No	Cursor for backward pagination.
`first`	integer	No	Number of notes to return for forward pagination.
`last`	integer	No	Number of notes to return for backward pagination.

Each returned note includes its discussion ID, so related notes can be grouped into threads.

Example:

Show me all comments on merge request 5 in project gitlab-org/gitlab

`add_branch`

Adds a branch to a GitLab project from a source ref.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL of the project. Provide this, or `project_id`.
`project_id`	string	No	ID or path of the project. Required if `url` is not provided.
`branch`	string	Yes	Name of the new branch.
`ref`	string	Yes	Branch name or commit SHA to create the new branch from.

Example:

Create a branch named feature/x from main in project gitlab-org/gitlab

`get_repository_file`

Retrieves the contents of a single file from a repository at a specific ref.

Content comes from the repository, not from your local filesystem. The file is returned as committed at ref, so uncommitted changes in a local checkout are not included.

Parameter	Type	Required	Description
`url`	string	No	URL of the file, for example `https://gitlab.example.com/my-group/my-project/-/blob/main/app/models/user.rb`. Provide this, or `project_id`, `file_path`, and `ref`.
`project_id`	string	No	ID or full path of the project. Required if `url` is not provided.
`file_path`	string	No	Path of the file relative to the repository root. Required if `url` is not provided.
`ref`	string	No	Branch name, tag name, or commit SHA. Use `HEAD` for the default branch. Required if `url` is not provided.
`offset`	integer	No	Zero-indexed line to start reading from. Default is `0`.
`limit`	integer	No	Maximum number of lines to return. Default and maximum are `2000`.

The response contains a metadata object with total_lines, returned_lines, truncated, and size_bytes. When the response covers only part of the file, system_instruction states the offset to use in the next call.

This tool returns text only. Binary files and files stored in Git LFS return an error. Files that a project excludes from GitLab Duo context also return an error.

Example:

Show me app/models/user.rb from the main branch of my-group/my-project

`get_pipeline`

Retrieves a pipeline, and optionally its jobs, downstream pipelines, or bridge (trigger) jobs.

Parameter	Type	Required	Description
`id`	string	Yes	ID or full path of the project.
`pipeline_id`	integer	Yes	ID of the pipeline.
`include`	array	No	Facet to include alongside the pipeline, one per call: `jobs`, `downstream_pipelines`, or `bridge_jobs`.
`job_status`	string	No	Filters the `jobs` facet by status (for example, `failed`). Only applies when `include` is `jobs`.
`first`	integer	No	Number of items to return for the selected `include` facet. Default is `20`, maximum is `100`.
`after`	string	No	Cursor for forward pagination of the selected `include` facet. Use the previous response’s `page_info.end_cursor`.

A bridge job’s downstream_pipeline is omitted (null) both when the trigger job hasn’t triggered a downstream pipeline yet, and when you don’t have access to that pipeline.

Each downstream pipeline includes a project_full_path, because a downstream pipeline can belong to a different project. Use that value as the id of a follow-up call.

Examples:

Get a pipeline:

Get the status of pipeline 12345 in project gitlab-org/gitlab

Get a pipeline’s failed jobs:

Show me the failed jobs in pipeline 12345 for project gitlab-org/gitlab

Get a pipeline’s downstream pipelines:

Show me the downstream pipelines triggered by pipeline 12345 in project gitlab-org/gitlab

`get_pipeline_jobs`

Retrieves the jobs for a specific GitLab CI/CD pipeline. To get jobs alongside the rest of the pipeline’s data in a single call, use the get_pipeline tool with include: jobs instead.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`pipeline_id`	integer	Yes	ID of the pipeline.
`per_page`	integer	No	Number of jobs per page.
`page`	integer	No	Current page number.

Example:

Show me all jobs in pipeline 12345 for project gitlab-org/gitlab

`get_job_log`

Retrieves the trace (log output) for a specific CI/CD job.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`job_id`	integer	Yes	ID of the job.

Example:

Show me the log output for job 88 in project gitlab-org/gitlab

`list_pipelines`

Lists pipelines in a GitLab project, with optional filters.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`ref`	string	No	Branch or tag name. Filters pipelines by ref.
`status`	string	No	Filters pipelines by status (for example, `running`, `success`, `failed`).
`source`	string	No	Filters pipelines by source (for example, `push`, `web`, `schedule`).
`created_after`	string	No	Returns pipelines created after the specified datetime (ISO 8601 format).
`created_before`	string	No	Returns pipelines created before the specified datetime (ISO 8601 format).
`order_by`	string	No	Orders pipelines by `id`, `status`, `ref`, `updated_at`, or `user_id`. Default is `id`.
`sort`	string	No	Sort direction, `asc` or `desc`. Default is `desc`.
`page`	integer	No	Current page number. Default is `1`.
`per_page`	integer	No	Number of items per page. Default is `20`.

Child pipelines are excluded from the results by default. To return only child pipelines, set source to parent_pipeline.

The default order (id, desc) returns pipelines with the highest ID first. ID order usually matches creation order, but the two aren’t guaranteed to agree. Use created_after or created_before to filter by an explicit time boundary. A caller can page through results and stop at the first pipeline outside its target range.

Example:

List all failed pipelines on the main branch for project gitlab-org/gitlab

`save_pipeline`

Runs, retries, or cancels a CI/CD pipeline in a GitLab project. To update pipeline metadata or delete a pipeline, use the manage_pipeline tool instead. To list pipelines, use the list_pipelines tool instead.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL of the project. Used only to create a pipeline. Provide this, or `project_id`.
`project_id`	string	No	ID or full path of the project. Used only to create a pipeline. Provide this, or `url`.
`pipeline_id`	integer	No	ID of an existing pipeline to target. When set, requires `action`. Omit to create a new pipeline.
`action`	string	No	Lifecycle action to perform on `pipeline_id`: `retry` or `cancel`. Required when `pipeline_id` is set.
`ref`	string	No	Branch or tag name. Required to create a pipeline (when `pipeline_id` is absent).
`variables`	array	No	Pipeline variables in array format (`[{key, value, variable_type}]`).
`inputs`	hash	No	Pipeline input parameters as key-value pairs.

Examples:

Create a pipeline:

Create a pipeline on the main branch for project gitlab-org/gitlab

Retry a pipeline:

Retry failed jobs in pipeline 12345 for project gitlab-org/gitlab

Cancel a pipeline:

Cancel pipeline 12345 in project gitlab-org/gitlab

`manage_pipeline`

Updates pipeline metadata or deletes a pipeline in a GitLab project. To create, retry, or cancel a pipeline, use the save_pipeline tool instead. To list pipelines, use the list_pipelines tool instead.

Parameter	Type	Required	Description
`id`	string	Yes	ID or URL-encoded path of the project.
`pipeline_id`	integer	Yes	ID of the pipeline. If only this parameter is set, deletes a pipeline and all related data.
`name`	string	No	Name of the pipeline. If this parameter and `pipeline_id` are set, updates the pipeline metadata.

Examples:

Update a pipeline:

Rename pipeline 12345 to "My deploy pipeline" in project gitlab-org/gitlab

Delete a pipeline:

Delete pipeline 12345 in project gitlab-org/gitlab

`create_workitem_note`

Creates a new note (comment) on a GitLab work item.

Parameter	Type	Required	Description
`body`	string	Yes	Content of the note.
`url`	string	No	URL for the work item. Required if `group_id` or `project_id` and `work_item_iid` are missing.
`group_id`	string	No	ID or path of the group. Required if `url` and `project_id` are missing.
`project_id`	string	No	ID or path of the project. Required if `url` and `group_id` are missing.
`work_item_iid`	integer	No	Internal ID of the work item. Required if `url` is missing.
`internal`	boolean	No	Marks the note as internal (visible only to users with the Reporter, Developer, Maintainer, or Owner role for the project). Default is `false`.
`discussion_id`	string	No	Global ID of the discussion to reply to (in the format `gid://gitlab/Discussion/<id>`).

Example:

Add a comment "This looks good to me" to work item 42 in project gitlab-org/gitlab

`get_workitem_notes`

Retrieves all notes (comments) for a specific GitLab work item.

Parameter	Type	Required	Description
`url`	string	No	URL for the work item. Required if `group_id` or `project_id` and `work_item_iid` are missing.
`group_id`	string	No	ID or path of the group. Required if `url` and `project_id` are missing.
`project_id`	string	No	ID or path of the project. Required if `url` and `group_id` are missing.
`work_item_iid`	integer	No	Internal ID of the work item. Required if `url` is missing.
`after`	string	No	Cursor for forward pagination.
`before`	string	No	Cursor for backward pagination.
`first`	integer	No	Number of notes to return for forward pagination.
`last`	integer	No	Number of notes to return for backward pagination.

Example:

Show me all comments on work item 42 in project gitlab-org/gitlab

`link_work_items`

Links a work item to one or more other work items with a relationship type.

Parameter	Type	Required	Description
`work_items_ids`	array of strings	Yes	Global IDs of the work items to link to (in the format `gid://gitlab/WorkItem/<id>`). Maximum 10 items.
`url`	string	No	URL for the source work item. Required if `group_id` or `project_id` and `work_item_iid` are missing.
`group_id`	string	No	ID or path of the group. Required if `url` and `project_id` are missing.
`project_id`	string	No	ID or path of the project. Required if `url` and `group_id` are missing.
`work_item_iid`	integer	No	Internal ID of the source work item. Required if `url` is missing.
`link_type`	string	No	Type of relationship. One of `relates_to`, `blocks`, or `blocked_by`. Default is `relates_to`. The `blocks` and `blocked_by` types require GitLab Premium or Ultimate.

Example:

Mark work item 42 in project gitlab-org/gitlab as blocked by work item 40

`get_saved_view_work_items`

Retrieves a saved view and its list of work items from a namespace. The tool applies the filters and the sort order in the saved view to the returned work items.

Parameter	Type	Required	Description
`saved_view_id`	string	Yes	Global ID of the saved view (in the format `gid://gitlab/WorkItems::SavedViews::SavedView/<id>`).
`url`	string	No	URL for the namespace (project or group). Required if `group_id` or `project_id` is missing.
`group_id`	string	No	ID or path of the group. Required if `url` and `project_id` are missing.
`project_id`	string	No	ID or path of the project. Required if `url` and `group_id` are missing.
`after`	string	No	Cursor for forward pagination.
`first`	integer	No	Number of work items to return. Maximum 100.

Example:

Show me the work items in this saved view: <URL>

`search`

Searches for a term across the entire GitLab instance with the search API. This tool is available for global, group, and project search. Available scopes depend on the search type.

Parameter	Type	Required	Description
`scope`	string	Yes	Search scope (for example, `work_items`, `merge_requests`, or `projects`).
`search`	string	Yes	Search term.
`group_id`	string	No	ID or URL-encoded path of the group you want to search.
`project_id`	string	No	ID or URL-encoded path of the project you want to search.
`state`	string	No	State of search results (for `work_items` and `merge_requests`).
`confidential`	boolean	No	Filters results by confidentiality (for `work_items`). Default is `false`.
`fields`	array of strings	No	Array of fields you want to search (for `work_items` and `merge_requests`).
`order_by`	string	No	Attribute to order results by. Default is `created_at` for basic search and relevance for advanced search.
`sort`	string	No	Sort direction for results. Default is `desc`.
`per_page`	integer	No	Number of results per page. Default is `20`.
`page`	integer	No	Current page number. Default is `1`.

Example:

Search issues for "flaky test" across GitLab

`search_labels`

Searches for labels in a GitLab project or group.

Parameter	Type	Required	Description
`full_path`	string	Yes	Full path of the project or group (for example, `group/project`).
`is_project`	boolean	Yes	Whether to search in a project (`true`) or group (`false`).
`search`	string	No	Search term to filter labels by title.

When you search group labels, the results include labels from ancestor and descendant groups.

Example:

Show me all labels in project gitlab-org/gitlab

`list_wiki_pages`

Lists the wiki pages in a GitLab project or group.

Parameter	Type	Required	Description
`project_id`	string	No	Full path or numeric ID of the project (for example, `gitlab-org/gitlab` or `278964`).
`group_id`	string	No	Full path or numeric ID of the group (for example, `gitlab-org` or `9970`).
`first`	integer	No	Number of wiki pages to return for forward pagination (maximum 100).
`after`	string	No	Cursor for forward pagination.

Provide only one project_id or group_id. Each call returns a single page of results. If more pages exist, the response includes an end_cursor you can pass as after to fetch the next page.

Example:

List the wiki pages in gitlab-org/gitlab

`semantic_code_search`

Add-on: GitLab Duo Core, Pro, or Enterprise
Offering: GitLab.com, GitLab Self-Managed

Introduced as an experiment in GitLab 18.5 with a feature flag named code_snippet_search_graphqlapi. Disabled by default.
Search by project path added in GitLab 18.6.
Changed from experiment to beta in GitLab 18.7. Feature flag code_snippet_search_graphqlapi removed.
Added to the GitLab UI in GitLab 18.7 with a feature flag named mcp_client. Disabled by default.
Updated to use the REST API in GitLab 18.11 with a feature flag named mcp_semantic_code_search_use_rest_api. Disabled by default.
Using the REST API generally available in GitLab 19.1. Feature flag mcp_semantic_code_search_use_rest_api removed.

The availability of this feature is controlled by a feature flag. For more information, see the history.

Searches for relevant code snippets in a GitLab project. For more information, including setup and enablement, see semantic code search.

Parameter	Type	Required	Description
`semantic_query`	string	Yes	Search query for the code.
`project_id`	string	Yes	ID or path of the project.
`directory_path`	string	No	Path of the directory (for example, `app/services/`).
`knn`	integer	No	Number of nearest neighbors used to find similar code snippets. Default is `64`.
`limit`	integer	No	Maximum number of results to return. Default is `20`.

For best results, describe the functionality or behavior you’re interested in rather than using generic keywords or specific function or variable names.

Example:

How are authorizations managed in this project?

`attach_scan_profile`

Attaches the given security scan profile to the specified projects, or to all projects under the specified groups.

Parameter	Type	Required	Description
`security_scan_profile_id`	string	Yes	Global ID of the security scan profile (for example, `gid://gitlab/Security::ScanProfile/1`).
`project_ids`	array of strings	No	Array of global IDs of projects (for example, `[gid://gitlab/Project/1]`). This is required unless `group_ids` is provided.
`group_ids`	array of strings	No	Array of global IDs of groups (for example, `[gid://gitlab/Group/1]`). This is required unless `project_ids` is provided.

Example:

Attach `gid://gitlab/Security::ScanProfile/1` to all projects under `gid://gitlab/Group/1`.