GitLab MCP server tools

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

Warning

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

Version history

Returns the current version of the GitLab MCP server.

Example:

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

create_issue

Version history

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

Version history

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

Version history

  • Introduced in GitLab 18.5.
  • assignee_ids, reviewer_ids, description, labels, and milestone_id added in GitLab 18.8.

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

Version history

  • Introduced in GitLab 18.4.
  • Changed to accept url and return associated data facets in GitLab 19.3.

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

  • Introduced in GitLab 19.3. create_branch is also accepted as an alias.

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

  • Introduced in GitLab 18.10.
  • Removed the list action in favor of the list_pipelines tool in GitLab 19.3.
  • Removed the create, retry, and cancel actions in favor of the save_pipeline tool in GitLab 19.3.

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

Version history

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

Version history

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

Version history

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

Version history

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

Version history

  • Introduced in GitLab 18.4.
  • Searching groups and projects and ordering and sorting results added in GitLab 18.6.
  • Renamed from gitlab_search to search in GitLab 18.8.

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

Version history

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

Version history

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

Version history

[!flag] 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

Version history

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`.