GitLab MCP server

The GitLab MCP (Model Context Protocol) server provides a bridge between AI assistants and GitLab repositories, allowing AI tools to interact with GitLab projects, issues, merge requests, and more. This improved version includes bug fixes and enhancements over the original server.

Installation and Setup

Using with npx

You can run the GitLab MCP server using npx without installing it globally:

{
  "mcpServers": {
    "GitLab communication server": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

Using with Docker

Standard Mode (stdio)

{
  "mcpServers": {
    "GitLab communication server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "-e",
        "GITLAB_READ_ONLY_MODE",
        "-e",
        "USE_GITLAB_WIKI",
        "-e",
        "USE_MILESTONE",
        "-e",
        "USE_PIPELINE",
        "iwakitakuma/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

SSE Mode

First, run the Docker container:

docker run -i --rm \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  iwakitakuma/gitlab-mcp

Then configure your MCP client:

{
  "mcpServers": {
    "GitLab communication server": {
      "url": "http://localhost:3333/sse"
    }
  }
}

Configuration Options

Environment Variables

The GitLab MCP server can be configured with these environment variables:

• GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token (required)
• GITLAB_API_URL: Your GitLab API URL (default: https://gitlab.com/api/v4)
• GITLAB_READ_ONLY_MODE: When set to 'true', restricts to read-only operations
• USE_GITLAB_WIKI: Set to 'true' to enable wiki-related tools
• USE_MILESTONE: Set to 'true' to enable milestone-related tools
• USE_PIPELINE: Set to 'true' to enable pipeline-related tools
• GITLAB_AUTH_COOKIE_PATH: Path to an authentication cookie file for GitLab instances requiring cookie-based authentication

Available Tools

The server provides over 65 tools for interacting with GitLab, including:

Repository Management

• Create or update files
• Search repositories
• Create repositories
• Get file contents
• Push multiple files
• Create branches
• Fork repositories

Issues and Merge Requests

• Create and manage issues
• Create and update merge requests
• Add comments and discussion threads
• Get diffs and changes
• List issues with filtering options

Wiki and Labels

• List, create, update, and delete wiki pages
• Manage project labels

CI/CD Pipelines

• List pipelines
• Get pipeline details
• Manage pipeline jobs
• Create, retry, and cancel pipelines

Project and Namespace Management

• List and verify namespaces
• Get project details
• List projects and group projects

Milestones

• Create and manage milestones
• Get issues and merge requests associated with milestones
• Get milestone burndown events

Each tool accepts specific parameters and returns structured data from the GitLab API.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.