Skip to content
GitLab MCP Server

Usage Examples

CI/CD WorkflowsStep-by-step pipeline monitoring and management
Code Review WorkflowsMR lifecycle, review, and approval
Issue ManagementTriage, tracking, and project management

This is a quick reference of natural language prompts you can use with any AI assistant connected to GitLab MCP Server, grouped by domain. Type the prompt in plain English and the server translates it into the right GitLab API operation automatically. The tabs below show which catalog action each prompt maps to: the action you would pass to gitlab_execute_action on the default dynamic surface, which is also the matching domain meta-tool’s action when GITLAB_MCP_TOOL_SURFACE=meta. They cover project management, code review, CI/CD, releases, and search.

Before you start

Section titled “Before you start”

The examples assume the server is already connected to your client, as Getting Started describes: on stdio the client starts it with GITLAB_TOKEN in its environment, plus GITLAB_URL for a self-managed instance. To share one server among several clients, start it in HTTP mode instead:

Terminal window
./gitlab-mcp-server --http \
  --gitlab-url=https://gitlab.com \
  --http-addr=:8080 \
  --max-http-clients=100

Replace https://gitlab.com with your self-managed instance’s URL when needed. Clients connect to http://<host>:8080/mcp and send their own GitLab token with every request, as Authorization: Bearer <token> or PRIVATE-TOKEN: <token>. --max-http-clients bounds how many distinct token and GitLab URL pairs the server keeps at once (100 is the default). Before other machines reach it, serve it over TLS or behind a proxy, as HTTP Server Mode describes.

List your projects

Section titled “List your projects”

Prompt: “Show me my GitLab projects”

The assistant runs project.list (gitlab_project with action: list when GITLAB_MCP_TOOL_SURFACE=meta), returning project names, descriptions, and URLs.

Create an issue

Section titled “Create an issue”

Prompt: “Create a bug report in my-group/my-project titled ‘Login page returns 404 after password reset’ with labels bug and priority::high”

The assistant runs issue.create (gitlab_issue with action: create on the meta surface), setting the title, description, labels, and project in a single operation. When the request leaves out the project or the labels, the assistant may ask for them before it creates the issue.

Manage labels

Section titled “Manage labels”

Prompt: “List all labels in the frontend project and create a new label called ‘accessibility’ with color #0052CC”

The assistant first runs project.label_list to show existing labels, then project.label_create to add the new one (gitlab_project with action: label_list and action: label_create on the meta surface).

Track milestones

Section titled “Track milestones”

Prompt: “Show me the progress on the Sprint 14 milestone in my-project”

The assistant runs project.milestone_get (gitlab_project with action: milestone_get on the meta surface), returning the milestone’s state, dates and web URL, and project.milestone_issues for the issues still open in it.

Manage members

Section titled “Manage members”

Prompt: “List all members of the frontend project and their access levels”

The assistant runs project.members (gitlab_project with action: members on the meta surface), returning team members with their roles and permissions.

Dynamic-first tool flow

Section titled “Dynamic-first tool flow”

Dynamic mode is the default, so the prompts above never name a tool directly. The assistant first discovers the action and its schema with gitlab_find_action, then runs it with gitlab_execute_action using a canonical domain.action ID:

gitlab_find_action → query: "list open merge requests"
gitlab_execute_action → action: "merge_request.list", params: { project_id: "42", state: "opened" }

When a pipeline fails, the same flow chains two actions — find the failing jobs, then read one job’s log:

gitlab_find_action → query: "list failed jobs in a pipeline"
gitlab_execute_action → action: "job.list", params: { project_id: "42", pipeline_id: 8847, scope: ["failed"] }
gitlab_execute_action → action: "job.trace", params: { project_id: "42", job_id: 501 }

Discover actions and projects

Section titled “Discover actions and projects”

To see what a domain covers on the default dynamic surface, search the catalog or read the tool manifest resource:

User: "What can I do with merge requests?"
→ gitlab_find_action → query: "merge request"        ranked actions with their input schemas
→ read gitlab://tools and keep the merge_request.* entries
→ read gitlab://tools/merge_request.list              one action's call shape and input schema

To list your own projects, the assistant runs project.list with owned: true (gitlab_project_list with GITLAB_MCP_TOOL_SURFACE=individual). Inside a cloned repository it can skip the question of which project you mean: discover_project.resolve maps the git remote to its GitLab project and returns its ID, path, web URL and default branch:

gitlab_execute_action → action: "discover_project.resolve", params: { remote_url: "git@gitlab.example.com:my-group/backend.git" }

Pass the remote exactly as git remote -v prints it, scheme or git@ prefix included; a bare group/project path is already a valid project_id and needs no resolving. With GITLAB_MCP_TOOL_SURFACE=meta or individual the same action is the standalone gitlab_discover_project tool.

On the meta surface

Section titled “On the meta surface”

With GITLAB_MCP_TOOL_SURFACE=meta, 34 tools serve a Free or CE instance. The catalog grows with the tier: 40 on self-managed Premium and 51 on self-managed Ultimate, one more of each on GitLab.com, where gitlab_orbit is served from Premium up (41 on GitLab.com Premium, 52 on GitLab.com Ultimate). Each domain tool takes only the top-level keys action and params:

Resource: gitlab://tools/gitlab_project
→ the gitlab_project tool's entry: its description, which carries the guidance for each action, and its input schema


Resource: gitlab://tools/gitlab_merge_request.list
→ one action's call shape and input schema


Call: gitlab_merge_request → { action: "list", params: { project_id: "42" } }
→ dispatches to the merge_request.list route

The domain tools on every tier are access, achievement, admin, branch, ci_catalog, ci_variable, custom_emoji, environment, feature_flags, group, issue, job, merge_request, model_registry, mr_review, package, pipeline, project, release, repository, runner, search, server, snippet, storage_move, tag, template, user and wiki, each served as gitlab_<domain>, beside the standalone gitlab_discover_project and the four gitlab_interactive_* creation flows. Labels, milestones and members are actions on gitlab_project (label_list, milestone_get, members) and on gitlab_group (group_label_list, group_milestone_get, members); merge request diffs and discussions are actions on gitlab_mr_review (changes_get, discussion_list); CI lint is gitlab_template with action: lint. Meta-tools describes the surface in full.

Dashboards and reports

Section titled “Dashboards and reports”

MCP prompts gather the GitLab data for a recurring question and hand it to the model ready to summarize. Clients usually offer them as slash commands or in a prompt picker; they are registered on the default full capability surface, and Resources & Prompts lists all 37.

A personal dashboard:

my_open_mrs()                    → your open MRs across projects, as author or assignee
my_pending_reviews()             → open MRs waiting for your review
my_issues()                      → issues assigned to you, with overdue detection
daily_standup(project_id="42")   → your last 24 hours in one project: done, planned, blockers

A manager’s dashboard:

team_overview(group_id="7")                → group members with open MR counts and recent merges
reviewer_workload(group_id="7")            → how many open MRs each member is reviewing
group_mr_dashboard(group_id="7")           → the group's MRs by project, with state and target branch filters
user_activity_report(username="johndoe")   → one user's events, merged MRs and reviews

A project’s health:

project_health_check(project_id="42")
→ latest pipeline status, open merge requests, branch hygiene and recommendations


stale_items_report(project_id="42", stale_days="30")
→ MRs and issues not updated for 30 days (14 when stale_days is left out)


milestone_progress(project_id="42")
→ issue and MR completion and due-date risk for every active milestone

When something is not found

Section titled “When something is not found”

When project.get and the get actions of the other common domains find nothing, they answer with a result marked isError: true instead of a protocol error, and say what to try next. Asked for project 999, project.get returns this text on every surface:

## ❓ Project Not Found


The project **999** does not exist or is not accessible with your current permissions.


---
💡 **Next steps:**
- Use project.list to search for projects by name or path
- Verify the project ID or URL-encoded path is correct (e.g. 'group%2Fproject')
- The project may have been deleted or you may lack access

Error Handling covers the other kinds of failure.

Frequently asked questions

What can I ask an AI assistant to do with GitLab MCP Server?

Anything the GitLab REST v4 and GraphQL APIs expose — 868 operations on Community Edition and up to 1,094 on GitLab.com. In practice that means listing and creating projects and issues, reviewing merge requests, checking and retrying pipelines, cutting releases, managing labels and milestones, searching code across a group, and administering members. You phrase the request in natural language and the server resolves it to one canonical GitLab action.

Do I need to know the tool names to use GitLab MCP Server?

No. In the default dynamic surface you describe what you want and the assistant calls gitlab_find_action to locate the matching action and its exact schema, then gitlab_execute_action to run it. Tool names such as gitlab_issue only become visible if you switch to GITLAB_MCP_TOOL_SURFACE=meta or GITLAB_MCP_TOOL_SURFACE=individual, which trade startup context for a browsable tool list.

How do I tell the assistant which GitLab project to use?

Pass the project path in project_id, in group/project form — for example my-group/backend. Numeric project IDs work too. If you are working inside a checked-out repository, the project discovery action maps the git remote URL to the right GitLab project so you do not have to state it at all: discover_project.resolve through gitlab_execute_action on the default surface, or the standalone gitlab_discover_project tool with GITLAB_MCP_TOOL_SURFACE=meta or individual.

Will an AI assistant change my GitLab data without asking?

Not without a safeguard being turned off. Destructive actions require explicit confirmation before they execute, GITLAB_MCP_READ_ONLY=true removes every mutating action from the catalog entirely, and GITLAB_MCP_SAFE_MODE=true intercepts mutations and returns a preview card naming the action, with the arguments it would have sent in a JSON block, instead of applying it. Read operations such as listing and searching are always safe.

Maintained by GitHubLinkedInMastodonGoogle ScholarAll projects