gitlab-ci-mcp

by mshegolev

Overview Schema Source Related Servers Discussions Admin

Python

Remote

gitlab_list_merge_requests

Read-onlyIdempotent

List merge requests of a GitLab project, optionally filtered by state (opened, closed, merged, locked, all).

Instructions

List merge requests of a project, optionally filtered by state.

Examples: - "What MRs are open right now" → default (state='opened') - "What merged last week" → state='merged' then filter by updated_at client-side - "Everything regardless of state" → state='all' - Don't use when you have an MR IID — use gitlab_get_merge_request for detail.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "project_path": "<project_path>"
    },
    "name": "gitlab_list_merge_requests"
  }
}

Input Schema

Name	Required	Description	Default
`page`	No	1-based page number.
`state`	No	Filter by MR state.	opened
`per_page`	No	Items per page (1–100).
`project_path`	Yes	GitLab project path (e.g. 'my-org/my-repo'). Required by default. For legacy deployments only, set GITLAB_ALLOW_DEFAULT_PROJECT=true to use GITLAB_PROJECT_PATH when omitted.

Output Schema

Name	Required	Description	Default
`count`	Yes
`state`	Yes
`project`	Yes
`pagination`	Yes
`merge_requests`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 schema fields changedv0.5.5Nov 5, 2026

removedInput schema / properties / project_path / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / project_path / default
```
Removed value: -null
```

changedInput schema / properties / project_path / description

Previous value: -"GitLab project path (e.g. 'my-org/my-repo'). When omitted, the default from GITLAB_PROJECT_PATH env var is used."New value: +"GitLab project path (e.g. 'my-org/my-repo'). Required by default. For legacy deployments only, set GITLAB_ALLOW_DEFAULT_PROJECT=true to use GITLAB_PROJECT_PATH when omitted."

addedInput schema / properties / project_path / minLength
```
Added value: +1
```
addedInput schema / properties / project_path / type
```
Added value: +"string"
```
addedInput schema / required
```
Added value: +[
+  "project_path"
+]
```

First observedv0.5.1Apr 17, 2026

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnly, idempotent, non-destructive and open-world, so safety is covered. The description adds value beyond that by disclosing the default state ('opened') and, importantly, that no server-side date filter exists — date-bounded questions require client-side filtering of updated_at, which an agent would otherwise get wrong.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The core purpose is front-loaded in one sentence, and the examples are terse and each earns its place by mapping a phrasing to a parameter. Slightly list-heavy and the backtick-heavy formatting is noisy, but nothing is redundant.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a read-only list tool with a full output schema and fully documented parameters, the description covers the gaps that matter: state semantics, the absence of date filtering, and the sibling alternative. Pagination behavior is left to the schema, which is a reasonable division of labor but leaves a small gap for an agent aggregating across pages.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds real meaning: it clarifies that 'opened' is the implicit default in practice, that 'all' means unfiltered across states, and that updated_at is not a filter parameter. It does not repeat the page/per_page mechanics, which the schema already documents well.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('List merge requests of a project') plus the scope modifier ('optionally filtered by state'), so the agent knows exactly what it retrieves. The closing line explicitly contrasts it with gitlab_get_merge_request, which is the nearest ambiguous sibling.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides three concrete intent-to-parameter mappings ('open right now' → default, 'merged last week' → state='merged' plus client-side updated_at filtering, 'everything' → state='all'). It also gives an explicit when-not rule: if you already have an MR IID, use gitlab_get_merge_request instead.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.