How to connect GitLab MCP with Python

Read a file from inside the artifacts archive of a CI/CD job as text. To discover what a job or pipeline produced, use get_job or get_pipeline with include: artifacts. For large files, page through with byte_offset and byte_limit.

Get a CI/CD job in a GitLab project. Add include: log to also get the job's trace/log, which you can page through with byte_offset and byte_limit. Add include: artifacts to also list the artifacts the job produced (name, size, file type); read one with the get_artifact_file tool.

Get the current version of MCP server.

List releases in a GitLab project, most recently released first. Identify the project with exactly one of url or project_id. Returns release metadata and asset links, not release assets themselves. Releases scheduled for a future date are omitted unless state is upcoming or all, and carry upcoming true when returned.

List tags in a GitLab project, most recently updated first. Identify the project with exactly one of url or project_id. When search is given, a tag whose name matches it exactly is listed first. Returns each tag name and its tip commit, not the tag message, commit diff, or file contents. When metadata.has_next_page is true, pass metadata.end_cursor as after to fetch the next page.

Merge a merge request, or schedule 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. Identify the merge request by url, or by project_id and merge_request_iid. To approve a merge request instead, use save_merge_request_review.

Add a branch to a GitLab project from a source ref. Examples: - Use branch and ref to create a new branch from an existing branch or commit SHA

Add a commit with one or more file actions to a project branch.

Get a single commit's metadata, optionally including its diff or notes. Identify the commit with either url, or project_id and commit_sha.

Get a merge request and optionally its diffs, commits, notes, pipelines, discussions, approvals, or conflicts. By default only the base merge request metadata is returned; request associated data through the `include` parameter so nothing extra is fetched unless asked for.

Read a file from a GitLab repository at a given ref. Reads from GitLab, not the local filesystem: use it for a project you have not checked out, or a specific branch, tag, or commit — not your local working copy. Returns the file as committed at ref. For large files, use offset and limit to read in windows; when the response is partial, system_instruction gives the next offset.

Get a CI/CD pipeline in a GitLab project, and optionally its jobs, downstream pipelines, bridge (trigger) jobs, or the artifacts its jobs produced. A bridge job's downstream pipeline is omitted if you do not have access to it. The artifacts facet pages over the pipeline's jobs; read one artifact file with the get_artifact_file tool. To list pipelines, use the list_pipelines tool instead.

Get metadata for a single GitLab project: numeric ID, full path, default branch, visibility, and web URL. Identify the project with exactly one of url or project_id. Use search with scope projects to find a project you cannot name yet.

Fetch a saved view and its work items list from a namespace

Get a single GitLab user. Use me: true to look up the authenticated user, for example to find your own user id before setting assignee_ids or reviewer_ids. Provide exactly one of username, id, or me. Returns the numeric id, username, name, state, and web URL.

Get a single work item (issue, epic, task, incident, objective, key result) with its type, dates, assignees, labels, milestone, and parent. Optionally include its notes, its discussions, or the merge requests related to it. Identify the work item by url, or by work_item_iid plus group_id or project_id. Widgets the work item type does not support are omitted.

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

Link a work item to other work items with a relationship type (relates_to, blocks, blocked_by)

List commits in a GitLab project, filtered by ref, author, path, or date. Identify the project with exactly one of url or project_id. Returns compact commit metadata; use get_commit for a single commit's diff or notes.

List GitLab groups. Without group_id, lists top-level groups where you are a member. With group_id, 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, this lists your groups at any depth). Archived groups and groups pending deletion are excluded. Useful for discovering group IDs and full paths for other tools.

List or search merge requests in a GitLab project or group by author, assignee, reviewer, state, milestone, labels, or text. Identify the project or group with exactly one of url, project_id, or group_id. Group results always include merge requests from subgroups. Returns compact merge request metadata; use get_merge_request for the full detail of a single merge request, or search for full-text search across resource types.

List GitLab projects. Without group_id, defaults to projects you have at least guest access to; 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. When group_id is given, the response includes subgroupsIncluded so you know which case applied.

List files and directories in a GitLab repository at a given path and ref. Identify the project with exactly one of url or project_id. Returns entry metadata only, never file contents; use get_repository_file to read a file. Each call returns up to 100 entries; when pageInfo.hasNextPage is true, pass pageInfo.endCursor as after to fetch the next page.

List the members of a GitLab project with their role and access level. Direct members only, unless include_inherited is true.

List or search work items (ISSUE, INCIDENT, TEST_CASE, REQUIREMENT, TASK, TICKET, OBJECTIVE, KEY_RESULT, EPIC) in a group or project. Filter by state, author, assignees, labels, milestone, dates, type, or free text. Group scope includes work items of descendant projects and subgroups. Each row carries only compact identifying fields: id, iid, title, state, web URL, reference, created and updated timestamps, and work item type. Use get_work_item for full details of one work item, including description, assignees, labels, and milestone.

Write merge request review artifacts as the authenticated user. Exactly one method per call: create_note adds a top-level comment; reply_discussion replies within 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 plus an optional summary in one call; post_duo_review asks GitLab Duo to review the merge request; approve records your approval (pass sha to avoid approving stale content); unapprove removes your approval. Identify the merge request by url, or by project_id and merge_request_iid. Each parameter below names the methods that use it.

Add a comment to a GitLab merge request or work item, or reply to an existing discussion thread. Identify the target with url, or with merge_request_iid or work_item_iid plus its project_id or group_id

Run, retry, cancel, or rename a CI/CD pipeline in a GitLab project. Omit pipeline_id and pass ref to run a new pipeline, and identify the project with exactly one of url or project_id. Pass pipeline_id with action to retry, cancel, or update an existing pipeline; update renames it and requires name.

Create or update 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.

Search labels in a GitLab project or group by multiple terms

Create a fork of a project

List all project pipelines

List all repository branches

Semantic (meaning-based) search over different types of content. Searches indexed project content using embedding-based similarity rather than keyword matching. Use this when you do not know the exact symbol or file name, or to discover how a behavior is implemented across the codebase. Primary use cases: - When you do not know the exact symbol or file path - To see how a behavior or feature is implemented across the codebase - To discover related implementations (clients, jobs, workers) How to use: - Provide a concise, specific query with concrete keywords - Use directory_path to narrow scope when scope is "code" - Prefer precise intent over broad terms Results are grouped by file. Each file includes merged line ranges with content and a relevance score (0.0-1.0). The response includes an overall confidence level (high/medium/low/unknown) based on score distribution. Requires semantic search to be enabled and indexed for the project namespace.

Search across GitLab with automatic selection of the best available search method. **Capabilities:** basic (keywords, file filters), advanced (boolean operators), exact code (exact match, regex, symbols) **Syntax Examples:** - Basic: "bug fix", "filename:*.rb", "extension:js" - Advanced: "bug AND critical", "display | banner", "#23456" - Exact code: "class User", "foo lang:ruby", "sym:initialize"

Create or update a merge request in a GitLab project. merge_request_iid alone decides the operation. Omitting it always creates a new merge request; provide it to update an existing one. - Create: omit merge_request_iid. title, source_branch, and target_branch are required. - Update: provide merge_request_iid. Use state_event (close or reopen) to change an existing merge request's state.