@weirdscience/mcp-gitlab

A Model Context Protocol (MCP) server that provides GitLab integration tools using the glab CLI. This server enables AI assistants to interact with GitLab repositories, issues, merge requests, and pipelines through a standardized MCP interface.

Features

• Issue Management: List, create, and manage GitLab issues

• Merge Requests: List and create merge requests

• Pipeline Monitoring: View project pipelines and their status

• Raw API Access: Direct access to GitLab REST API endpoints

• Multi-Instance Support: Works with gitlab.com and self-hosted GitLab instances

• Pagination Support: Automatic handling of large result sets

Related MCP server: GitLab Code Review MCP Server

Prerequisites

• Node.js 18+

• glab CLI tool installed and configured

• GitLab personal access token

Installation

Global Installation

npm install -g @weirdscience/mcp-gitlab

Local Installation

npm install @weirdscience/mcp-gitlab

Setup

1. Install glab CLI

First, install the glab CLI tool:

# macOS
brew install glab

# Linux
sudo apt install glab

# Windows
winget install GitLab.GLab

2. Configure glab

Authenticate with your GitLab instance:

# For gitlab.com
glab auth login

# For self-hosted GitLab
glab auth login --hostname gitlab.your-instance.com

3. Configure MCP

Add the server to your MCP configuration file (~/.config/mcp.json or similar):

{
  "mcpServers": {
    "gitlab-glab": {
      "command": "mcp-gitlab",
      "env": {
        "GITLAB_HOST": "gitlab.com",
        "GITLAB_TOKEN": "your-gitlab-token"
      }
    }
  }
}

Cursor Configuration

To use this MCP server with Cursor, you need to configure it in Cursor's settings:

Method 1: Global Configuration

1. Open Cursor's Command Palette (Cmd/Ctrl + Shift + P)

2. Search for "MCP" and select "MCP: Configure Servers"

3. Add a new server configuration:

{
  "name": "gitlab-glab",
  "command": "mcp-gitlab",
  "env": {
    "GITLAB_HOST": "gitlab.com",
    "GITLAB_TOKEN": "your-gitlab-token"
  }
}

Method 2: Workspace Configuration

Create a .cursorrules file in your project root:

{
  "mcpServers": {
    "gitlab-glab": {
      "command": "mcp-gitlab",
      "env": {
        "GITLAB_HOST": "gitlab.com",
        "GITLAB_TOKEN": "your-gitlab-token"
      }
    }
  }
}

Method 3: Settings UI

1. Open Cursor Settings (Cmd/Ctrl + ,)

2. Search for "MCP"

3. Add the server configuration in the MCP settings section

Verification

After configuration, you can verify the server is working by:

1. Opening Cursor's Command Palette

2. Running "MCP: List Available Tools"

3. You should see tools like gitlab.issues.list, gitlab.mrs.list, etc.

Usage in Cursor

Once configured, you can use GitLab tools directly in Cursor:

• Ask Cursor to "list open issues in my project"

• Request "create a merge request for the current branch"

• Ask "show me the latest pipeline status"

Cursor will automatically use the appropriate MCP tools to fulfill these requests.

Environment Variables

Available Tools

gitlab.issues.list

List issues for a project.

Parameters:

• project (string): Project path or numeric ID (e.g., 'gitlab-org/cli')

• state (optional): Issue state ('opened', 'closed', 'all')

• labels (optional): Comma-separated label names

• assignee (optional): Assignee username

gitlab.mrs.list

List merge requests for a project.

Parameters:

• project (string): Project path or numeric ID

• state (optional): MR state ('opened', 'merged', 'closed', 'all')

• labels (optional): Comma-separated label names

• draft (optional): Filter for draft MRs

gitlab.mr.create

Create a new merge request.

Parameters:

• project (string): Project path or numeric ID

• sourceBranch (string): Source branch name

• targetBranch (string): Target branch name

• title (string): MR title

• description (optional): MR description

• draft (optional): Create as draft MR

• labels (optional): Comma-separated labels

• assignees (optional): Comma-separated assignee usernames

gitlab.pipelines.list

List pipelines for a project.

Parameters:

• project (string): Project path or numeric ID

• page (optional): Page number (default: 1)

• perPage (optional): Items per page (default: 50, max: 100)

• status (optional): Pipeline status filter

gitlab.api

Low-level access to GitLab REST API.

Parameters:

• method (optional): HTTP method ('GET', 'POST', 'PUT', 'PATCH', 'DELETE')

• path (string): API path below /api/v4

• fields (optional): Request body fields

• headers (optional): Custom headers

glab.version

Get the installed glab CLI version.

Usage Examples

List Open Issues

{
  "tool": "gitlab.issues.list",
  "arguments": {
    "project": "gitlab-org/cli",
    "state": "opened"
  }
}

Create Merge Request

{
  "tool": "gitlab.mr.create",
  "arguments": {
    "project": "my-group/my-project",
    "sourceBranch": "feature/new-feature",
    "targetBranch": "main",
    "title": "Add new feature",
    "description": "This PR adds a new feature to improve user experience.",
    "labels": "enhancement,frontend"
  }
}

Get Project Pipelines

{
  "tool": "gitlab.pipelines.list",
  "arguments": {
    "project": "my-group/my-project",
    "perPage": 10,
    "status": "success"
  }
}

Development

Prerequisites

• Node.js 18+

• npm or yarn

Setup

git clone https://github.com/weirdscience/mcp-gitlab.git
cd mcp-gitlab
npm install

Build

npm run build

Development Mode

npm run dev

Testing

npm run check

Linting

npm run lint
npm run lint:fix

Formatting

npm run format

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

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

Acknowledgments

• Model Context Protocol for the MCP specification

• glab CLI for GitLab command-line interface

• GitLab for the GitLab platform

Support

If you encounter any issues or have questions:

1. Check the GitHub Issues

2. Review the glab CLI documentation

3. Consult the MCP documentation

Changelog

0.1.0

• Initial release

• Basic GitLab integration via glab CLI

• Support for issues, merge requests, and pipelines

• Raw API access capability