GitLab MCP Server

Create Merge Request

create_merge_request

Create a new GitLab merge request by specifying the project path, source branch, target branch, and title, with an optional description and credentials.

Instructions

Create a new merge request in a GitLab project (requires user authentication with write permissions)

Input Schema

Name	Required	Description
`title`	Yes	Title of the merge request
`description`	No	Description of the merge request
`projectPath`	Yes	Full path of the project (e.g., "group/project-name")
`sourceBranch`	Yes	Source branch name
`targetBranch`	Yes	Target branch name
`userCredentials`	No	Your GitLab credentials (optional — falls back to the configured env token if not provided)

Output Schema

Name	Required	Description	Default
`id`	Yes
`iid`	Yes
`title`	Yes
`webUrl`	Yes

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": {
+    "id": {
+      "type": "string"
+    },
+    "iid": {
+      "type": "string"
+    },
+    "title": {
+      "type": "string"
+    },
+    "webUrl": {
+      "type": "string"
+    }
+  },
+  "required": [
+    "id",
+    "iid",
+    "title",
+    "webUrl"
+  ],
+  "type": "object"
+}

Changed1 schema field changedv1.15.0May 10, 2026

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=false, idempotentHint=false, and destructiveHint=false, so the safety profile is covered. The description adds the auth/permission requirement, which is genuinely useful context, but says nothing about what a repeat call does, what happens when the source branch is missing, or whether the MR is created as draft.

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?

A single front-loaded sentence with the auth caveat attached — zero waste and nothing buried. It is, however, thin enough that conciseness shades into under-specification rather than crispness.

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?

With an output schema present and full parameter coverage, the description needn't explain returns or fields. But for a mutating create tool, it leaves unaddressed obvious agent questions — duplicate-MR behavior, branch-missing failure, and draft support — so it is only minimally complete.

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% and every parameter carries its own description, including the userCredentials env-token fallback, so the schema carries the burden. The description adds no meaning beyond that, which is the expected baseline-3 outcome at full coverage.

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?

States a specific verb+resource ("Create a new merge request in a GitLab project"), which is unambiguous and clearly the write counterpart to update_merge_request. It does not explicitly differentiate itself from sibling write paths like execute_rest_write or the update variant, keeping it short of a 5.

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?

The parenthetical "requires user authentication with write permissions" gives a real precondition for use, but there is no guidance on when to pick this tool versus update_merge_request or a generic REST write, and no exclusions. Usage is implied rather than stated.

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

Deploy Server