mikedotJS/mcp-gitlab

@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

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 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