GitLab MCP server tools

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?

get_project

Returns metadata for a single GitLab project: numeric ID, full path, default branch, visibility, and web URL.

default_branch is null when the project has no repository yet. To find a project you cannot name yet, use search with the projects scope.

Example:

What is the default branch of gitlab-org/gitlab?

add_commit

Adds a commit with one or more file actions to a branch in a single call.

Each object in actions accepts the following fields:

Partial edits replace exactly one occurrence of old_str. If it occurs more than once, provide more surrounding context. Partial edits read the complete file on the server, so they are not supported for files larger than 10 MiB. For larger files, commit the full file content instead.

Partial edits are not supported for binary files or for files stored in LFS.

Example:

In project gitlab-org/gitlab, create README.md on branch "docs-update"
with the content "# New title" and commit message "Add README"

create_issue

Superseded by save_work_item, which resolves milestone titles and label names in the same places (the project and its ancestor groups) but is stricter about names it cannot find: create_issue creates label names that don’t exist yet and silently drops an unknown milestone title, while save_work_item returns an error naming anything it cannot find. This tool no longer appears in tools/list but remains callable while callers migrate.

Creates a new issue in a GitLab project.

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

Superseded by get_work_item, which covers issues and other work item types. This tool no longer appears in tools/list but remains callable while callers migrate.

Retrieves detailed information about a specific GitLab 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.

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, discussions, or conflicts. Only the base merge request is returned unless you request associated data with the include parameter.

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

The conflicts facet returns raw conflict file content, including Git conflict markers. It is available only when the merge request cannot be merged and you can push to the source branch, and is null until mergeability has been checked. Read the base conflicts field to determine the state.

Example:

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

start_duo_session

Starts a GitLab Duo Agent Platform session that runs a flow from the AI Catalog, and returns the session ID. Only catalog flows can be started this way, because only those sessions can later be answered with send_duo_session_input.

The session runs in a CI job that can push commits and open merge requests. The response includes a suggested polling delay; use get_duo_session with the returned workflow_id to follow progress.

Example:

Run the Developer flow in project 42 to add tests for the parser

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.

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

get_duo_session

Checks the status of a GitLab Duo Agent Platform session. Running sessions include a suggested polling delay. Finished sessions and completed chat turns include the latest agent answer. Sessions waiting for approval include instructions for continuing the session.

Example:

Check the status of Duo session 42

send_duo_session_input

Answers a GitLab Duo Agent Platform session that is waiting for input: approves or rejects a pending plan or tool call, or replies to a question the agent asked. Only sessions with status input_required whose last CI job has finished accept input. Sessions with status plan_approval_required or tool_call_approval_required cannot be answered over MCP yet.

The session continues in a CI job. The response includes a suggested polling delay; use get_duo_session with the same workflow_id to follow progress.

Example:

Approve the plan for Duo session 42 and tell it to also add tests

list_merge_requests

Lists or searches merge requests in a GitLab project or group, returning compact merge request metadata. Group scope always includes merge requests from every project in the group and its subgroups, but excludes merge requests from archived projects. A group result also includes the owning project path of each merge request, for use with get_merge_request.

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.

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.

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.

Example:

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

get_merge_request_conflicts

Retrieves the merge conflict content for a merge request that cannot be merged. Returns the raw Git conflict markers (<<<<<<<, =======, and >>>>>>>) exactly as they appear in the conflicted files. Each file’s content is grouped under a # File: heading. For renamed files, the heading shows the path in each branch.

You must have permission to push to the source branch of the merge request. The tool returns an error when the merge request has no conflicts, when its mergeability has not been checked yet, or when a branch or diff ref is missing.

Example:

Show the conflicts for merge request 42 in project gitlab-org/gitlab

save_note

Adds a comment to a GitLab merge request or work item, or replies to an existing discussion thread, as the authenticated user.

Examples:

• Comment on a merge request:

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

• Comment on a work item:

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

get_merge_request_notes

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

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:

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.

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.

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?

get_user

Gets a single GitLab user. Use this tool to resolve a username, or your own account, to a numeric user ID. For example, use it before you set assignees or reviewers with other tools.

Provide exactly one of username, id, or me.

The response returns the user’s numeric id, username, name, state, and web_url.

Example:

What is my GitLab user ID?

accept_merge_request

Merges a merge request, or schedules it to merge automatically. Without strategy, the merge starts immediately and completes asynchronously. With strategy, auto-merge is armed and the merge request merges once its checks pass. To approve a merge request instead, use the save_merge_request_review tool.

Calls against a merge request that is already merged succeed with status already_merged, and calls with a strategy against a merge request that is already scheduled succeed with status already_scheduled.

Example:

Merge merge request 42 in project gitlab-org/gitlab once its checks pass, and remove the source branch

add_branch

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

Example:

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

fork_repository

Forks a GitLab project into a namespace.

The fork is created asynchronously. The response contains the new project attributes, including an import_status field, such as scheduled, that shows fork progress.

The call fails due to reasons based on the following statuses:

• 409 status when the namespace already has a fork of the project.
• 404 status when the project or namespace doesn’t exist, or you don’t have permission to fork the project.

Example:

Fork gitlab-org/gitlab-test into my personal namespace

list_branches

Lists the branches of a GitLab project, optionally filtered by name.

Example:

List branches in gitlab-org/gitlab whose names contain "release"

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.

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

list_repository_tree

Lists the files and directories in a GitLab repository at a given path and ref. Returns entry metadata only, never file contents. To read the contents of a file, use get_repository_file.

Each call returns up to 100 entries. When pageInfo.hasNextPage is true, pass pageInfo.endCursor as after to fetch the next page.

Example:

List the files under app/services in gitlab-org/gitlab on the default branch

get_commit

Retrieves a single commit’s metadata, and optionally its diff or 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

list_commits

Lists the commits of a GitLab project, optionally filtered by ref, author, path, or date. Returns compact commit metadata. To get the diff or notes of a single commit, use get_commit.

Each commit costs a Gitaly call when with_stats is true, so first defaults to 10 and must not exceed 10 when with_stats is set.

Example:

List commits to app/models in gitlab-org/gitlab since 2026-08-01 by Alex

list_releases

Lists releases in a GitLab project, most recently released first.

Provide exactly one of url or project_id.

Each entry returns release metadata only: tag_name, name, released_at, upcoming, and assets. assets holds a count of the release’s asset links and up to five of those links. When a release has more than five, count reports the real total. Source archives are excluded, because they are derivable from the tag.

The response also carries a metadata object with page, per_page, and has_more. Use has_more to decide whether to request the next page.

Release notes are intentionally not returned in this response.

A release with a future released_at is scheduled rather than published, and sorts ahead of published releases. Use state to control which you get. Scheduled releases carry upcoming set to true.

To read the commit a release is built on, pass its tag_name to the get_commit tool. To download an asset, use the url from assets.links.

Example:

List the most recent releases for project gitlab-org/gitlab

list_tags

Lists tags in a GitLab project, most recently updated first. If search matches a tag name exactly, GitLab lists that tag first.

Provide exactly one of url or project_id.

Each entry returns name and commit, where commit holds the tag’s tip commit sha and title. commit is null for a tag that points at something other than a commit.

Tag messages are intentionally not returned in this response.

The response also carries a metadata object with has_next_page and end_cursor. When has_next_page is true, pass end_cursor as after to fetch the next page.

To read the full commit a tag points at, use the get_commit tool.

Example:

List the most recent tags for the gitlab-org/gitlab project

get_pipeline

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

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.

The artifacts facet returns a flat list of artifacts. Each artifact carries its name, size, file_type, expiry information, and the job_id and job_name of the job that produced it. Pagination pages over the pipeline’s jobs, not over the artifacts.

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 the artifacts a pipeline produced:

  List the artifacts of 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.

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 or the artifacts it produced.

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.

The artifacts facet lists every artifact the job produced, with its name, size, file_type, and expiry information.

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

• Get a job’s artifacts:

  What artifacts did job 88 in project gitlab-org/gitlab produce?

get_artifact_file

Reads a file from inside the artifacts archive of a CI/CD job as text. To discover what a job or pipeline produced, use the get_job or get_pipeline tool with include: artifacts.

The tool reads from the archive artifact only. Report artifacts stored as separate files, such as junit or dotenv artifacts, are not part of the archive and cannot be read with this tool.

When the file is longer than byte_limit, the response reports the total size and tells you the byte_offset to use for the next window. Binary files are not returned; the error names the file, its size and type, and where to view it in the browser.

Examples:

• Read a test report from a job’s artifacts:

  Read coverage/index.html from the artifacts of job 88 in project gitlab-org/gitlab

• Investigate a failed end-to-end test:

  Find the JUnit report in the artifacts of job 88 in gitlab-org/gitlab and summarize the failures

list_pipelines

Lists pipelines in a GitLab project, with optional filters.

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, cancels, or renames a CI/CD pipeline in a GitLab project. To delete a pipeline, use the manage_pipeline tool instead. To list pipelines, use the list_pipelines tool instead.

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

• Rename a pipeline:

  Rename pipeline 12345 to "Nightly security scan" 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.

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.

The notes facet returns up to 100 notes per call and paginates in both directions with the notes_* parameters. 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

get_workitem_notes

Superseded by get_work_item with include: ["notes"], which paginates notes in both directions. This tool no longer appears in tools/list but remains callable while callers migrate.

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

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.

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.

Example:

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

save_vulnerability

Performs write operations on a vulnerability in a GitLab project.

Examples:

• Dismiss a vulnerability:

  Dismiss vulnerability 123 with reason FALSE_POSITIVE

• Confirm a vulnerability:

  Mark vulnerability 456 as confirmed

• Revert to detected:

  Revert vulnerability 789 back to detected state

• Update severity:

  Change severity of vulnerability 321 to CRITICAL with comment "Reassessed based on new intel"

• Create an issue:

  Create an issue for vulnerability 654 in project gitlab-org/gitlab

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.

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.

Example:

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

get_work_item_types

Lists the work item types available in a namespace (group or project), including system-defined types (such as Issue, Epic, and Task) and custom types. Each returned type includes its global ID, name, icon, and the widget types enabled on it, so you can avoid setting fields the type does not support.

Example:

List the work item types available in the gitlab-org group

list_projects

Without group_id, lists projects where you have at least the Guest role by default; pass min_access_level to raise the threshold. With group_id, lists every project in that group and its subgroups regardless of access level; adding min_access_level or visibility narrows the listing to that group only, not its subgroups, because GitLab does not support combining subgroup traversal with those filters when listing a group’s projects.

When you provide group_id, the response includes subgroupsIncluded: true when the listing covers the group’s subgroups, false when min_access_level or visibility narrowed the listing to that group only.

Example:

List my projects

list_groups

Lists groups, for navigating the group hierarchy and discovering group IDs and full paths to use with other tools. Without group_id, this tool lists top-level groups where you are a member. With group_id, it lists the direct subgroups of that group, regardless of membership. Set include_subgroups to true to recurse into all descendant subgroups. With no group_id, that lists your groups at any depth. Archived groups and groups pending deletion are excluded.

Example:

List the subgroups of gitlab-org

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.

Example:

Search issues for "flaky test" across GitLab

search_labels

Searches for labels in a GitLab project or group.

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.

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_search

Searches relevant content in a GitLab project by meaning rather than by keyword. Use this tool when you do not know the exact symbol or file name, or to discover how a behavior is implemented across a codebase. For more information, including setup and enablement, see semantic code search.

Results are grouped by file. Each file includes merged line ranges with content and a relevance score. 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.

Example:

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