← Back to project

GitLab MCP Agent Skill Specification



This report defines the MCP tool set for GitLab, including method signatures, parameter schemas, return types, and examples. The tools are designed to be intuitive for AI agents while covering common GitLab workflows.

---

Conventions



---


Tool Definitions



Projects



#### gitlab.list_projects

List accessible projects.

Params:


Result: `{ "projects": [ { "id": number, "name": string, "path": string, "web_url": string } ] }`


Example:

json

{

  "jsonrpc": "2.0",

  "method": "gitlab.list_projects",

  "params": { "owned": true },

  "id": 1

}


#### gitlab.get_project

Get details of a specific project.

Params:


Result: `{ "id": number, "name": string, "description": string, "default_branch": string, "web_url": string, ... }`


---

Issues



#### gitlab.list_issues

List issues for a project.

Params:


Result: `{ "issues": [ { "iid": number, "title": string, "description": string, "state": string, "labels": [string], "assignee": { "id": number, "name": string }, "web_url": string } ] }`


Notes: `iid` is the project‑level issue number. Combine with `project` to reference.

#### gitlab.create_issue

Create a new issue.

Params:


Result: `{ "issue": { "iid": number, "web_url": string } }`


#### gitlab.update_issue

Update an existing issue.

Params:


Result: `{ "updated": true }`


#### gitlab.close_issue

Shortcut to close an issue.

Params:


Result: `{ "closed": true }`


---

Merge Requests



#### gitlab.list_merge_requests

List merge requests.

Params:


Result: `{ "merge_requests": [ { "iid": number, "title": string, "source_branch": string, "target_branch": string, "state": string, "web_url": string, "assignee"? } ] }`


#### gitlab.create_merge_request

Create a new merge request.

Params:


Result: `{ "mr": { "iid": number, "web_url": string } }`


#### gitlab.merge_merge_request

Accept and merge a merge request.

Params:


Result: `{ "merged": true, "sha": string }`


#### gitlab.approve_merge_request

Add an approval from the current user.

Params:


Result: `{ "approved": true }`


---

Repository Files



#### gitlab.upsert_file

Create or update a file in the repository.

Params:


Result: `{ "sha": string, "web_url": string }`


Idempotency: If file exists and content matches current, return existing SHA; else update.

#### gitlab.get_file

Retrieve a file’s contents and metadata.

Params:


Result: `{ "content": string (base64 decoded), "encoding": "base64", "sha": string, "file_path": string }`


Note: We decode base64 for convenience; agent receives plain text.

#### gitlab.delete_file

Delete a file.

Params:


Result: `{ "deleted": true }`


---

CI/CD



#### gitlab.list_pipelines

List pipelines for a project or ref.

Params:


Result: `{ "pipelines": [ { "id": number, "sha": string, "ref": string, "status": string, "web_url": string } ] }`


#### gitlab.trigger_pipeline

Create a new pipeline for a ref.

Params:


Result: `{ "pipeline": { "id": number, "web_url": string } }`


#### gitlab.list_pipeline_jobs

List jobs in a pipeline.

Params:


Result: `{ "jobs": [ { "id": number, "name": string, "status": string, "stage": string, "web_url": string } ] }`


#### gitlab.play_job

Trigger a manual job.

Params:


Result: `{ "started": true }`


---

Error Handling



Common error codes (drawn from GitLab):


MCP error objects:
json

{

  "code": 404,

  "message": "Project not found: 'mygroup%2Fmyproj'"

}


---

Security Considerations



---


Implementation Notes



---


Word count: ~1,200