gitlab-mcp

GitLab MCP

A Model Context Protocol (MCP) server for GitLab, enabling Claude to interact directly with your GitLab instance.

[!warning] ⚠️ This is an unofficial project. It is not endorsed or supported by GitLab Inc. and is not recommended for use in production environments.

💬 Feedback

Please provide feedback in https://gitlab.com/gitlab-org/ux-research/-/issues/3495, or (if you don't have access) open a new issue at https://gitlab.com/fforster/gitlab-mcp/-/issues.

Overview

GitLab MCP implements the Model Context Protocol for GitLab, allowing AI assistants like Claude to access and manipulate GitLab resources. This integration enables Claude to work with:

• Discussions and Notes
• Epics
• Issues
• Jobs
• Merge Requests
• Repository Files and Directories
• Snippets
• User information

Installation

Option 1: Install from Homebrew

This is the simplest way to install gitlab-mcp when you're on Mac.

# Add the gitlab-mcp tap repository
brew tap fforster/gitlab-mcp https://gitlab.com/fforster/homebrew-gitlab-mcp.git

# Install gitlab-mcp
brew install gitlab-mcp

Option 2: Download Precompiled Binaries

The GitLab Releases page contains pre-built binaries for Linux, Mac OS, and Windows, for x86_64 and ARM64 architectures.

Download the appropriate .tar.gz file, extract it, and you will find the binary in the extracted directory. The binary does not depend on any other files.

Option 3: Build from source

This is recommended if you plan on contributing features or bug fixes to gitlab-mcp.

1. Clone this repository
2. Build the binary with go build, this creates gitlab-mcp in the current directory. Use -o <path> to chose a different filename (or directory).

Option 4: Docker

A pre-built Docker image is available:

# Use with gitlab.com (default)
docker run -i -e GITLAB_TOKEN=your_gitlab_token registry.gitlab.com/fforster/gitlab-mcp:latest

# Use with custom GitLab instance
docker run -i -e GITLAB_TOKEN=your_gitlab_token -e GITLAB_URL=https://gitlab.example.com registry.gitlab.com/fforster/gitlab-mcp:latest

Authentication

gitlab-mcp offers two authentication methods:

• OAuth2 Token (preferred)
• Personal Access Token

OAuth2 Token

Run gitlab-mcp auth to generate an OAuth2 token. This is the preferred method because it expires in a few days, reducing the risk of your token being exposed or misused.

# Run the OAuth flow to obtain tokens
$ gitlab-mcp auth
Please visit the following URL to authorize the application:
https://gitlab.com/oauth/device?user_code=WDJB-MJHT

Waiting to retrieve an access token...
Success.

The command prints an authentication URL. Follow the link and authorize the application to complete the flow. gitlab-mcp will automatically detect when you have completed the OAuth flow and will then store the access token in a file.

For custom GitLab instances, use the --base-url flag to specify the URL of the GitLab instance. For example:

gitlab-mcp auth --base-url https://gitlab.example.com

Personal Access Token

Alternatively, gitlab-mcp can use a personal access token for authentication. Generate one from your GitLab User Settings with the api scope, or read_api for read-only access.

Once created, ensure the token is available to gitlab-mcp in the environment variable GITLAB_TOKEN.

Usage with Claude Desktop

To use the GitLab MCP server with Claude Desktop, add the following to your Claude Desktop configuration file:

Using the binary

{
  "mcpServers": {
    "GitLab": {
      "command": "/opt/homebrew/bin/gitlab-mcp",
    }
  }
}

Using Docker

{
  "mcpServers": {
    "GitLab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--pull=always",
        "-e", "GITLAB_TOKEN",
        "-e", "GITLAB_URL",
        "registry.gitlab.com/fforster/gitlab-mcp:latest"
      ],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_URL": "https://gitlab.example.com"
      }
    }
  }
}

[!note] Remove the GITLAB_URL environment variable from both args and env sections to use the default gitlab.com instance.

Explanation:

• -i is required so Docker keeps STDIN open.
• --rm cleans up the container when gitlab-mcp exits.
• --pull=always ensures that Docker downloads the latest version of gitlab-mcp before running.
• -e GITLAB_TOKEN exports the GITLAB_TOKEN environment variable to gitlab-mcp.
• -e GITLAB_URL exports the GITLAB_URL environment variable for custom GitLab instances (optional).

Config file location

The configuration file is typically located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Environment Variables

GitLab MCP supports the following environment variables:

• GITLAB_TOKEN: Your GitLab personal access token with api (or read_api for read-only) scope. Prefer to create an OAuth token using gitlab-mcp auth instead, which does not require any configuration via environment variables.
• GITLAB_URL: Custom GitLab instance URL (defaults to https://gitlab.com/api/v4).
  • Must use HTTPS scheme for security
  • Example: https://gitlab.example.com

You can provide these environment variables in one of two ways:

1. Directly in the configuration, by adding an env section to the configuration:

   {
     "mcpServers": {
       "GitLab": {
         "command": "/opt/homebrew/bin/gitlab-mcp",
         "env": {
           "GITLAB_TOKEN": "your_gitlab_token",
           "GITLAB_URL": "https://gitlab.example.com"
         }
       }
     }
   }
   

2. Via shell initialization files, where your .bashrc or similar file sets the environment variables:

   {
     "mcpServers": {
       "GitLab": {
         "command": "/bin/bash",
         "args": [
           "-c",
           "/opt/homebrew/bin/gitlab-mcp"
         ]
       }
     }
   }
   

Supported Tools

Example Usage

Once configured, you can ask Claude to interact with your GitLab instance:

• "Prioritize the open issues assigned to me."
• "List the merge requests I need to review."
• "Add a comment to issue #42 suggesting a possible solution."
• "Summarize the discussion of issue #123 in the my-project project."
• "Create a new snippet with the code I just shared."
• "What epics are currently open in the my-group group?"
• "Please explain why the pipeline of merge request !456 failed."
• "How do I use the MCP server according to the README.md file in the fforster/gitlab-mcp GitLab project."
• "On GitLab, what have reprazent and ffoster been working on between 2025-04-28 and 2025-05-02?"
• "List all of my pending todos."
• "List the latest 100 completed todos."

License

This project is licensed under the MIT License - see the LICENSE file for details.