Help us learn about your current experience with the documentation. Take the survey.

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

`save_merge_request`

Creates or updates a merge request in a GitLab project. The presence of merge_request_iid selects the operation: omit it to create a merge request, or provide it to update an existing one.

Parameter	Type	Required	Description
`project_id`	string	Yes	ID or full path of the project.
`merge_request_iid`	integer	No	Internal ID of the merge request. Provide to update an existing merge request; omit to create one.
`title`	string	No	Title of the merge request. Required when creating.
`source_branch`	string	No	Name of the source branch. Required when creating.
`target_branch`	string	No	Name of the target branch. Required when creating.
`target_project_id`	integer	No	ID of the target project. Applies when creating.
`description`	string	No	Description of the merge request.
`labels`	array of strings	No	Label names. Replaces all existing labels. Pass an empty array to remove all labels.
`add_labels`	array of strings	No	Label names to add. Applies when updating.
`remove_labels`	array of strings	No	Label names to remove. Applies when updating.
`assignees`	array of strings	No	Usernames to assign. Alternative to `assignee_ids`; provide one. Pass an empty array to remove all assignees.
`assignee_ids`	array of integers	No	User IDs to assign. Alternative to `assignees`; provide one. Pass an empty array to remove all assignees.
`reviewers`	array of strings	No	Usernames to request review from. Alternative to `reviewer_ids`; provide one. Pass an empty array to remove all reviewers.
`reviewer_ids`	array of integers	No	User IDs to request review from. Alternative to `reviewers`; provide one. Pass an empty array to remove all reviewers.
`milestone_id`	integer	No	ID of the milestone.
`milestone`	string	No	Title of a project or ancestor-group milestone to assign. Mutually exclusive with `milestone_id`.
`remove_source_branch`	boolean	No	Remove the source branch when the merge request is merged.
`squash`	boolean	No	Squash commits into a single commit when merging.
`state_event`	string	No	State transition to perform. One of `close` or `reopen`. Applies when updating.
`discussion_locked`	boolean	No	Lock the merge request discussion. Applies when updating.
`allow_collaboration`	boolean	No	Allow commits from members who can merge to the target branch. Applies when updating.

Examples:

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

Update merge request 42 in project gitlab-org/gitlab to add the "bug" label and close it

`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

`save_merge_request_review`

Writes merge request review artifacts as the authenticated user. Each call performs exactly one operation, selected with the method parameter:

Method	Action
`create_note`	Adds a top-level comment.
`reply_discussion`	Replies in an existing discussion.
`create_diff_note`	Comments on a specific diff line.
`resolve_discussion`	Resolves or unresolves a discussion.
`submit_review`	Posts multiple diff comments and an optional summary in one call.
`post_duo_review`	Asks GitLab Duo to review the merge request. Requires GitLab Duo Code Review.
`approve`	Approves the merge request. Already-approved calls succeed with status `already_approved`.
`unapprove`	Removes your approval. Calls without a prior approval succeed with status `not_approved`.

Responses from post_duo_review, approve, and unapprove include the merge request’s current diff_head_sha, so you can tell whether a standing approval or review still covers the latest commits.

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 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.
`method`	string	Yes	The operation to perform. Parameters that belong to a different method are rejected.
`body`	string	No	Note text. Required for `create_note`, `reply_discussion`, and `create_diff_note`. Lines cannot start with `/` to avoid triggering quick actions (for example, `/merge`).
`discussion_id`	string	No	Discussion to act on. Required for `reply_discussion` and `resolve_discussion`. Accepts a global ID or a bare discussion ID.
`internal`	boolean	No	For `create_note`, marks the note as internal.
`resolved`	boolean	No	For `resolve_discussion`: `true` resolves, `false` unresolves. Required for that method.
`old_path`	string	No	For `create_diff_note`, the file path before the change. Provide `old_path` or `new_path`, or both.
`new_path`	string	No	For `create_diff_note`, the file path after the change.
`old_line`	integer	No	For `create_diff_note`, the line number in the old version. Provide `old_line` or `new_line`, or both.
`new_line`	integer	No	For `create_diff_note`, the line number in the new version.
`comments`	array	No	For `submit_review`, 1-20 diff comments. Each entry takes `file` and `body` (required), and `old_line`, `new_line`, and `suggestion` (optional). Required for that method. `file` is the post-change path; for renamed files, use `create_diff_note` instead.
`verdict`	string	No	For `submit_review`, an overall verdict prefixed to the summary note.
`summary`	string	No	For `submit_review`, a summary note posted after the diff comments.
`summary_internal`	boolean	No	For `submit_review`, marks the summary note as internal.
`sha`	string	No	For `approve`, a head SHA guard. When given and it no longer matches the merge request head, the approval is refused. Pass the full 40-character `diff_head_sha` returned by `get_merge_request`.

Example:

Review merge request 42 in project gitlab-org/gitlab and leave your findings as diff comments with a summary

`list_project_members`

Lists the members of a GitLab project with their role and access level.

Parameter	Type	Required	Description
`project_id`	string	Yes	Full path or numeric ID of the project (for example, `gitlab-org/gitlab` or `278964`).
`include_inherited`	boolean	No	Also return members who inherit their role from a parent group or a subgroup of the project. Defaults to `false`.
`query`	string	No	Return only members whose name or username contains this text.
`first`	integer	No	Number of members to return for forward pagination (default 20, maximum 100).
`after`	string	No	Cursor for forward pagination.

For each member, the response returns the user ID, username, name, numeric access_level, the matching access_level_name (for example, Maintainer), and the membership expires_at date. Members who were invited by email but have not accepted their invitation yet are not returned.

Each call returns a single page of results. If more pages exist, the response metadata includes an end_cursor you can pass as after to fetch the next page.

Example:

Who are the maintainers of 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_commit`

Retrieves a single commit’s metadata, and optionally its diff or notes.

Parameter	Type	Required	Description
`url`	string	No	URL of the GitLab commit. Required if `project_id` and `commit_sha` are not provided.
`project_id`	string	No	ID or URL-encoded path of the project. Required if `url` is not provided.
`commit_sha`	string	No	Commit to look up. Accepts a full or short SHA, branch name, or tag name. Required if `url` is not provided.
`include`	array	No	Associated facet to fetch inline, one per call (`diff` or `notes`). Base metadata is always returned.
`diff_detail`	string	No	Level of detail in the commit diff. Applies only when `include` contains `diff`. Can be either `stats` or `full_patch`. Default is `stats`.
`notes_after`	string	No	Token to fetch the next page of notes. Applies only when `include` contains `notes`.
`notes_first`	integer	No	Number of notes to return per page (maximum 100). Applies only when `include` contains `notes`.

With diff_detail set to stats, the diff facet returns per-file and summary line counts. With full_patch, it returns the patch text.

Example:

Show me commit abc123 in gitlab-org/gitlab with its diff stats

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

Gets a CI/CD job’s metadata, and optionally its trace/log.

Parameter	Type	Required	Description
`id`	string	Yes	ID or full path of the project.
`job_id`	integer	Yes	ID of the job.
`include`	array	No	Facet to include alongside the job, one per call: `log`.
`byte_offset`	integer	No	Byte offset to start reading the job’s log from. Only applies when `include` is `log`. Default is `0`.
`byte_limit`	integer	No	Maximum number of bytes of the job’s log to return. Only applies when `include` is `log`. Default and maximum is `512000`.

When the log is longer than byte_limit, the response reports the total size and tells you the byte_offset to use for the next window.

Examples:

Get a job’s metadata:

Get the status of job 88 in project gitlab-org/gitlab

Get a job’s log:

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

`get_work_item`

Retrieves a single work item (issue, epic, task, incident, objective, or key result) with its type, dates, assignees, labels, milestone, and parent. Optionally includes its notes or the merge requests related to it. Widgets the work item type does not support are omitted.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL of the work item (a `/-/work_items/` URL). Provide this, or `work_item_iid` with `group_id` or `project_id`.
`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.
`include`	array	No	Associated data to return. One of `notes` or `related_merge_requests`, one facet per call.
`related_merge_requests_first`	integer	No	Number of related merge requests to return. Default 20, maximum 100.
`related_merge_requests_after`	string	No	Cursor for forward pagination of related merge requests.
`mr_page_size`	integer	No	Deprecated: use `related_merge_requests_first` instead.
`mr_pagination_cursor`	string	No	Deprecated: use `related_merge_requests_after` instead.

The notes facet returns the first 100 notes. Use get_workitem_notes for full note pagination. The related_merge_requests facet is empty for group-level work items such as epics.

Example:

Get issue 42 in project gitlab-org/gitlab with its related merge requests

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

`save_work_item`

Creates or updates a GitLab work item, such as an issue, task, or epic. Omit work_item_iid to create a new work item. Provide work_item_iid or a work item URL to update an existing one. Send only the fields you intend to set, and omit the rest. The tool names create_work_item and update_work_item are aliases for this tool.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL for the project, group, or work item. Provide exactly one of `url`, `project_id`, or `group_id`.
`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	Positive internal ID of the work item to update. Omit to create a new work item.
`title`	string	No	Title of the work item. Required when creating a work item.
`type_name`	string	No	Work item type name, for example `Issue`, `Task`, or `Epic`. Required when creating a work item. Valid types depend on the namespace and license.
`description`	string	No	Description in GitLab Flavored Markdown. Maximum 1,048,576 characters.
`assignee_ids`	array of integers	No	User IDs to assign to the work item. Maximum 100 items.
`label_ids`	array of strings	No	Label IDs or global IDs. Create only; on update use `add_label_ids` or `remove_label_ids`. Maximum 100 items.
`add_label_ids`	array of strings	No	Update only. Label IDs or global IDs to add. Maximum 100 items.
`remove_label_ids`	array of strings	No	Update only. Label IDs or global IDs to remove. Maximum 100 items.
`confidential`	boolean	No	Sets the work item confidentiality.
`start_date`	string	No	Start date, in `YYYY-MM-DD` format.
`due_date`	string	No	Due date, in `YYYY-MM-DD` format.
`state`	string	No	Update only. `closed` closes the work item, `opened` reopens it.
`parent_id`	string	No	Global ID or numeric ID of the parent work item.
`todo_action`	string	No	Update only. `add` adds a to-do for the current user, `mark_as_done` marks to-dos as done.
`todo_id`	string	No	Update only. Global ID or numeric ID of the to-do. Omit to update all to-dos on the work item.
`health_status`	string	No	Health status. One of `onTrack`, `needsAttention`, or `atRisk`. Ultimate only.
`weight`	integer	No	Weight of the work item. Must be 0 or greater. Premium and Ultimate only.
`clear_weight`	boolean	No	Update only. Removes the weight. Takes precedence over `weight`. Premium and Ultimate only.
`status_id`	string	No	Global ID of the status to set. Premium and Ultimate only.
`is_fixed`	boolean	No	Whether start and due dates are fixed. When `false`, dates roll up from child items and `start_date` and `due_date` are ignored. Premium and Ultimate only.
`agent_plan`	string	No	Markdown content of the agent plan. Ultimate only. Requires the workplan feature.

Example:

Create a task "Update the onboarding guide" in project gitlab-org/gitlab and assign it to me

`list_work_items`

Lists or searches work items (issues, incidents, test cases, requirements, tasks, tickets, objectives, key results, epics) in a group or project. Group scope includes work items of descendant projects and subgroups. Each result contains only the ID, IID, title, state, web URL, full reference, created and updated timestamps, and work item type, with cursor pagination. Use get_work_item to read one work item in depth.

Parameter	Type	Required	Description
`url`	string	No	GitLab URL for the project or group. Provide exactly one of `url`, `group_id`, or `project_id`.
`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.
`state`	string	No	Filter by state: `opened`, `closed`, or `all` (default).
`search`	string	No	Free-text search in title and description.
`author_username`	string	No	Username of the author.
`assignee_usernames`	array	No	Usernames of assignees. A work item must match all of them. Maximum 100 values.
`label_name`	array	No	Label names. A work item must have all of them. Maximum 100 values.
`milestone_title`	array	No	Milestone titles. Cannot be combined with `milestone_wildcard_id`. Maximum 100 values.
`milestone_wildcard_id`	string	No	`NONE`, `ANY`, `STARTED`, or `UPCOMING`. Cannot be combined with `milestone_title`.
`types`	array	No	Work item types to include, for example `["ISSUE", "TASK"]`.
`created_after`	string	No	Created after this time (ISO 8601; date-only means start of day, offsets honored).
`created_before`	string	No	Created before this time (ISO 8601; date-only means start of day, offsets honored).
`updated_after`	string	No	Updated after this time (ISO 8601; date-only means start of day, offsets honored).
`updated_before`	string	No	Updated before this time (ISO 8601; date-only means start of day, offsets honored).
`due_after`	string	No	Due after this time (ISO 8601; date-only means start of day, offsets honored).
`due_before`	string	No	Due before this time (ISO 8601; date-only means start of day, offsets honored).
`sort`	string	No	Sort order, for example `UPDATED_DESC`. Default `CREATED_DESC`.
`first`	integer	No	Number of work items to return. Default 20, maximum 100.
`after`	string	No	Cursor for forward pagination.
`health_status_filter`	string	No	Ultimate only. `onTrack`, `needsAttention`, or `atRisk`.
`status`	object	No	Ultimate only. Filter by custom status name, for example `{"name": "In progress"}`.

Example:

List my open tasks in the gitlab-org group updated this month.

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