playbooks

home / mcp / gitlab mcp server

GitLab MCP Server

Provides access to GitLab projects, MRs, pipelines, commits, and more via MCP for AI-assisted workflows.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "nguyenvanduocit-gitlab-mcp": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "ghp_exampleTOKEN"
      }
    }
  }
}

GitLab MCP is a Go-based connector that lets you interact with GitLab repositories, projects, pipelines, and more through natural language. It enables AI assistants to perform common GitLab tasks directly, reducing context switching and speeding up workflows.

How to use

You connect your MCP client to a running GitLab MCP server (either via a local stdio server, a Docker-based deployment, or an HTTP server). Once connected, you can ask Claude to list projects, review merge requests, trigger pipelines, manage variables, search code, and monitor deployments using natural language. Your commands are interpreted by the MCP server and translated into GitLab API calls.

How to install

Prerequisites: you need a GitLab account with access to your instance, a personal access token, and an MCP-enabled Cursor client.

Step 1. Obtain a GitLab Personal Access Token - Go to your GitLab instance → User Settings → Access Tokens - Create a token with scopes: api, read_user, read_repository, write_repository - Copy the token (you won’t see it again) and keep it secure.

Step 2. Choose your installation method - Docker (recommended for easiest setup) - Binary download - Build from source (Go) if you want to customize the server.

Configure your MCP connection in Cursor

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run", "--rm", "-i",
        "-e", "GITLAB_URL=https://gitlab.com",
        "-e", "GITLAB_TOKEN=your-personal-access-token",
        "ghcr.io/nguyenvanduocit/gitlab-mcp:latest"
      ]
    }
  }
}
{
  "mcpServers": {
    "gitlab": {
      "command": "/usr/local/bin/gitlab-mcp",
      "env": {
        "GITLAB_URL": "https://gitlab.com",
        "GITLAB_TOKEN": "your-personal-access-token"
      }
    }
  }
}

If you run a self-hosted GitLab instance, replace the URL with your own (for example, https://gitlab.yourcompany.com).

Test your setup

Restart Cursor completely, then open a new chat with Claude. Try simple queries to verify data is returned from GitLab, for example listing groups, showing recent merge requests, or checking pipeline status.

Advanced options and HTTP mode

You can run the MCP server in HTTP mode for development or centralized access. Start the server on port 3000 and point Cursor to the HTTP URL.

# Start HTTP server on port 3000
gitlab-mcp -env .env -http_port 3000
```
```json
{
  "mcpServers": {
    "gitlab": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

Notes on troubleshooting

If you encounter authentication or connection errors, verify the GITLAB_URL includes https:// and that your GITLAB_TOKEN has the required scopes. If you see a message about missing MCP servers, restart Cursor and double-check the MCP configuration in Cursor settings.

Available tools

list_projects

List projects in a group with details and access levels

get_project

Get detailed information about a specific project

list_mrs

List merge requests with filtering options (state, author, target branch)

get_mr_details

Retrieve detailed MR information including changes, discussions, and approvals

create_mr

Create a new merge request with a title and description

create_mr_note

Add comments to a merge request to support discussions

list_mr_comments

List all comments on a merge request

get_mr_pipelines

Get pipelines associated with a merge request

get_mr_commits

Get the commit history for a merge request

rebase_mr

Rebase a merge request against the target branch

list_pipelines

List pipelines for a project with status and duration

get_pipeline

Get detailed information about a pipeline and its jobs

trigger_pipeline

Trigger a new pipeline with optional variables

list_project_jobs

List CI/CD jobs for a project

get_job

Get detailed information about a specific job, including logs and artifacts

cancel_job

Cancel a running job and monitor status

retry_job

Retry a failed job to re-run it

gitflow_create_release

Create release branches following Git Flow conventions

gitflow_finish_release

Finish releases by creating merge requests to develop and master

gitflow_create_feature

Create feature branches for development features

gitflow_finish_feature

Finish features by creating merge requests to develop

gitflow_create_hotfix

Create hotfix branches for urgent fixes

gitflow_finish_hotfix

Finish hotfixes by creating merge requests to both branches

gitflow_list_branches

List Git Flow branches by type

list_group_users

List members of a group and their roles

list_user_contribution_events

Show user activity events and contribution streams

list_groups

List accessible groups with filtering

list_group_variables

List variables at the group level with security information

create_group_variable

Create a new group-scoped variable with proper permissions

update_group_variable

Update an existing group variable

remove_group_variable

Remove a group variable

list_all_deploy_tokens

List all deploy tokens (admin) across projects and groups

list_group_deploy_tokens

List deploy tokens at the group level

get_group_deploy_token

Get details about a group deploy token

create_group_deploy_token

Create a new group deploy token with scopes and expiration

delete_group_deploy_token

Delete a group deploy token

list_project_deploy_tokens

List deploy tokens for a specific project

get_project_deploy_token

Get details about a project deploy token

create_project_deploy_token

Create a project deploy token with scopes and expiration

delete_project_deploy_token

Delete a project deploy token

search_global

Search across all GitLab content globally (issues, MRs, commits, code)

search_group

Search within a specific group

search_project

Search within a specific project

search_issues_global

Global search for issues across all groups/projects

search_merge_requests_global

Global search for merge requests

search_commits_global

Global search for commits

search_code_global

Global search for code

get_file_content

Get file content from a repository with branch/commit support

search_commits

Search commits by author, path, or date within a project

get_commit_details

Get detailed information about a specific commit

post_commit_comment

Add a comment to a commit for code review

get_commit_merge_requests

Get merge requests associated with a commit

cherry_pick_commit

Cherry-pick a commit to another branch

revert_commit

Revert a commit to undo changes

get_group_variable

Get details about a specific group variable

get_project_deploy_token

Get details about a project deploy token

delete_project_deploy_token

Delete a project deploy token