Skip to main content
The gitlab MCP adapter connects to the GitLab REST API v4. Use it to triage issues, create bug reports from workflow failures, and explore project metadata — on GitLab.com or self-managed instances.

​
Prerequisites

  • A GitLab account with access to the target projects or groups
  • A personal access token, group access token, or project access token with scopes such as api and read_api
  • For self-managed GitLab: the REST base URL for your instance (e.g. https://gitlab.example.com/api/v4)
  • project_contributor access in AgentRuntime

​
Connect in AgentRuntime

1

Create a GitLab access token

In GitLab, go to User Settings → Access Tokens (or create a group/project token). Grant at least read_api; add api if you need to create issues. Copy the token immediately — GitLab shows it only once.
2

Create a connection

Go to Connections and click New custom connection to create an API key connection with APIToken. For self-managed instances, also set BaseURL to your REST v4 base (e.g. https://gitlab.example.com/api/v4).
3

Add gitlab MCP instance

Go to MCP, click Add instance for gitlab, wire your connection on Instance config, set the profile active, and save.
4

Verify identity

Run mcp_call → get_current_user and list_projects before wiring project IDs into workflows.
See Authentication for binding connections to MCP instances.

​
What you can build

  • Incident → issue — Workflow failure step captures error context → LLM formats a title and body → create_issue in the on-call project.
  • Release notes triage — list_issues with state=opened → LLM summarizes blockers → post summary to Slack or Notion.
  • Project discovery — list_projects with search → agent picks the correct project_id_or_path for downstream API calls.
  • Custom automation — gitlab_api_call for merge requests, pipelines, or labels not covered by first-class tools.

​
Tools

ToolDescription
get_current_userGitLab user for the configured API token
list_projectsProjects visible to the token (optional name/path search)
get_projectProject by numeric ID or namespace path (e.g. group/project)
list_issuesIssues in a project with optional state filter
create_issueCreate an issue with title, description, and labels
gitlab_api_callRaw GitLab REST v4 request (GET, POST, PUT, PATCH, DELETE)

​
Example

Create an issue when a workflow step fails: 
{
  "id": "gitlab-issue",
  "type": "mcp_call",
  "name": "File GitLab issue",
  "tool_name": "create_issue",
  "tool_args": {
    "project_id_or_path": "my-group/my-service",
    "title": "Workflow run {{input.run_id}} failed",
    "description": "{{steps.summarize-error.result.summary}}",
    "labels": "automation,incident"
  },
  "depends_on": ["summarize-error"],
  "timeout_s": 30
}

​
Configuration

KeyRequiredDescription
APITokenYesPersonal, group, or project access token
BaseURLNoREST v4 base URL (default GitLab.com API)

​
Troubleshooting

IssueFix
401 UnauthorizedToken expired or revoked; create a new token with correct scopes
404 on project pathUse URL-encoded path (group%2Fproject) or numeric project ID
Self-managed SSL errorsConfirm BaseURL uses HTTPS and matches your instance hostname
403 on create_issueToken needs api scope, not just read_api