GitLab MCP Server

Search Issues

search_issues

Read-onlyIdempotent

Search issues using text queries and filters like assignee, author, labels, and state. Filter by criteria alone by leaving the search term empty.

Instructions

Search for issues with text search and/or structured filtering (assignee, author, labels, state). For filtering by assignee/author/labels without text search, leave searchTerm empty.

Input Schema

Name	Required	Description	Default
`sort`	No	Sort order (e.g., UPDATED_DESC, CREATED_DESC, CREATED_ASC). Defaults to UPDATED_DESC for recency.
`after`	No	Pagination cursor. To fetch the next page, pass the previous response pageInfo.endCursor here and repeat until pageInfo.hasNextPage is false. Paginating this way is the reliable path to complete results and accurate totals.
`first`	No	Number of issues to retrieve
`state`	No	Filter by issue state (opened, closed, all)	all
`fetchAll`	No	Fetch multiple pages in one call, up to "first" items total (max 100) — NOT exhaustive. For complete results or accurate counts, leave this false and paginate via after (pageInfo.endCursor).
`labelNames`	No	Filter by label names (e.g., ["Priority::High", "bug"])
`searchTerm`	No	Text search term (optional - leave empty to filter by assignee/author/labels only)
`projectPath`	No	Optional project path (e.g., "group/project"). Omit for global search.
`authorUsername`	No	Filter by author username (e.g., "cdhanlon")
`userCredentials`	No	Your GitLab credentials (optional — falls back to the configured env token if not provided)
`assigneeUsernames`	No	Filter by assignee usernames (e.g., ["cdhanlon", "jsmith"])

Output Schema

Name	Required	Description	Default
`nodes`	Yes
`hasMore`	No
`pageInfo`	Yes
`totalFetched`	No

Schema Changelog

Changes observed during successful MCP inspections.

Changed3 schema fields changedv4.0.0Nov 2, 2026

removedInput schema / additionalProperties
```
Removed value: -false
```

changedInput schema / properties / userCredentials / anyOf

Previous value: -[
-  {
-    "additionalProperties": false,
-    "properties": {
-      "accessToken": {
-        "minLength": 1,
-        "type": "string"
-      },
-      "gitlabUrl": {
-        "format": "uri",
-        "type": "string"
-      }
-    },
-    "type": "object"
-  },
-  {
-    "type": "null"
-  }
-]New value: +[
+  {
+    "properties": {
+      "accessToken": {
+        "minLength": 1,
+        "type": "string"
+      },
+      "gitlabUrl": {
+        "format": "uri",
+        "type": "string"
+      }
+    },
+    "type": "object"
+  },
+  {
+    "type": "null"
+  }
+]

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "additionalProperties": {},
+  "properties": {
+    "hasMore": {
+      "type": "boolean"
+    },
+    "nodes": {
+      "items": {
+        "additionalProperties": {},
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "iid": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "webUrl": {
+            "type": "string"
+          }
+        },
+        "required": [
+          "id",
+          "iid",
+          "title",
+          "webUrl"
+        ],
+        "type": "object"
+      },
+      "type": "array"
+    },
+    "pageInfo": {
+      "additionalProperties": {},
+      "properties": {
+        "endCursor": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "hasNextPage": {
+          "type": "boolean"
+        },
+        "hasPreviousPage": {
+          "type": "boolean"
+        },
+        "startCursor": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      },
+      "required": [
+        "hasNextPage",
+        "endCursor"
+      ],
+      "type": "object"
+    },
+    "totalFetched": {
+      "maximum": 9007199254740991,
+      "minimum": 0,
+      "type": "integer"
+    }
+  },
+  "required": [
+    "nodes",
+    "pageInfo"
+  ],
+  "type": "object"
+}

Changed2 schema fields changedv2.2.4Jul 24, 2026

changedInput schema / properties / after / description

Previous value: -"Cursor for pagination"New value: +"Pagination cursor. To fetch the next page, pass the previous response pageInfo.endCursor here and repeat until pageInfo.hasNextPage is false. Paginating this way is the reliable path to complete results and accurate totals."

changedInput schema / properties / fetchAll / description

Previous value: -"Fetch all pages up to 100 results"New value: +"Fetch multiple pages in one call, up to \"first\" items total (max 100) — NOT exhaustive. For complete results or accurate counts, leave this false and paginate via after (pageInfo.endCursor)."

Changed3 schema fields changedv1.15.0May 10, 2026

addedInput schema / properties / fetchAll

Added value: +{
+  "default": false,
+  "description": "Fetch all pages up to 100 results",
+  "type": "boolean"
+}

addedInput schema / properties / sort

Added value: +{
+  "description": "Sort order (e.g., UPDATED_DESC, CREATED_DESC, CREATED_ASC). Defaults to UPDATED_DESC for recency.",
+  "type": "string"
+}

changedInput schema / properties / userCredentials / description

Previous value: -"Your GitLab credentials (optional - uses shared token if not provided)"New value: +"Your GitLab credentials (optional — falls back to the configured env token if not provided)"

First observedv1.7.3Mar 7, 2026

TDQS

B3.4/5.0

Behavior3/5

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

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered without the description. The description contributes the combining semantics of text search and structured filters, but says nothing about pagination, result caps, or fetchAll trade-offs — those caveats live only in the schema, not in the description.

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?

Two sentences, front-loaded with the core capability and followed immediately by the one actionable tip. No filler, though the brevity leaves useful routing information unsaid.

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

Completeness3/5

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

An output schema exists and the input schema is richly annotated, so return values and parameter mechanics need not be repeated. What is missing is sibling disambiguation against get_issues, get_user_issues, and search_gitlab, which is the main open question for an agent choosing among many search-shaped tools.

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

Parameters3/5

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

Schema description coverage is 100%, so every one of the 11 parameters is already documented, including the important fetchAll/pagination distinction. The description's only parameter-related statement (leave searchTerm empty for filter-only queries) restates what the searchTerm schema text already says, adding no new meaning.

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

Purpose4/5

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

The description names a specific verb and resource ('Search for issues') and enumerates the supported filter dimensions (assignee, author, labels, state), so an agent knows exactly what the tool returns. It does not, however, distinguish itself from close siblings such as get_issues, get_user_issues, or search_gitlab, which an agent must disambiguate on its own.

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

Usage Guidelines3/5

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

'For filtering by assignee/author/labels without text search, leave searchTerm empty' is genuine usage guidance for one combination of inputs. But there is no statement about when to prefer this over get_issues, get_user_issues, or the broader search_gitlab, which is the harder routing decision in a ~50-tool namespace.

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

Deploy Server