Skip to main content
Glama

mcp-gitlab

by atla-digital
npmGitHub
TypeScript
MIT License
32
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

GitLab MCP Server

A Model Context Protocol (MCP) server that enables you to interact with your GitLab account. Get diffs, analyze merge requests, review code, cherry-pick changes, and more.

Features

This MCP server provides comprehensive tools for interacting with GitLab repositories, including:

Core Repository Features

  • Listing projects and retrieving details
  • Managing branches and repositories
  • Working with merge requests and diffs
  • Adding comments and internal notes to merge requests
  • Updating merge request attributes
  • Listing and working with issues
  • Getting and comparing repository file contents

Project Settings & Integrations

  • Managing project integrations and services
  • Configuring and controlling Slack integration
  • Setting up, updating, and testing webhooks

CI/CD Management

  • Working with pipeline trigger tokens
  • Managing CI/CD variables
  • Triggering and controlling pipelines

User & Group Administration

  • Listing and managing users
  • Working with groups and group memberships
  • Managing project members and access levels

🚀 Perfect Match: MCP-Workflow Integration

MCP-GitLab + MCP-Workflow = GitLab Development Superpowers!

This MCP server works seamlessly with MCP-Workflow to provide structured, workflow-driven GitLab development. Together, they deliver:

🔄 Structured GitLab Operations

  • Guided Development: Follow proven workflows for every GitLab operation
  • Code Review Excellence: Systematic merge request reviews with comprehensive feedback
  • Issue Management: Step-by-step issue analysis and resolution workflows

🎯 Workflow-Driven GitLab

  • Consistent Process: Every GitLab action follows established, repeatable workflows
  • Never Get Lost: Complex operations broken down into clear, sequential steps
  • Quality Assurance: Built-in validation and quality gates throughout

💡 Real-World Example

# 1. Agent uses MCP-Workflow to start "GitLab Merge Request Review" workflow_get_step("gitlab-mr-review") # 2. Workflow guides systematic MR analysis using this MCP server gitlab_get_merge_request(project_id="web/runner", merge_request_iid=45) gitlab_get_merge_request_changes(project_id="web/runner", merge_request_iid=45) # 3. Agent follows workflow to provide line-specific code feedback gitlab_create_merge_request_discussion( project_id="web/runner", merge_request_iid=45, body="Consider using a constant for this magic number", position={ base_sha: "abc123...", head_sha: "def456...", old_path: "src/utils.js", new_path: "src/utils.js", new_line: 42 } ) # 4. Workflow ensures comprehensive review completion workflow_get_step("review-completion-checklist")

🏆 Why This Combination Works

  • 🧭 Guided Navigation: MCP-Workflow provides the roadmap, this server provides the GitLab tools
  • 🔒 Consistency: Same high-quality process every time, regardless of project complexity
  • ⚡ Efficiency: No more wondering "what's next?" - structured workflows guide every step
  • 🎨 Flexibility: 29+ interconnected workflows covering every GitLab development scenario
  • 🔄 Context Preservation: Workflow state maintained across long development sessions
  • 🎯 Precision: Line-specific code comments with full GitLab discussion threading
  • 🛡️ Quality: Built-in review gates, security analysis, and best practice enforcement

Get Started: Install both MCP servers and experience structured GitLab development!

🔧 This MCP Server Provides

  • 70+ GitLab Tools: Complete API coverage for repositories, merge requests, issues, CI/CD, webhooks
  • Line-Level Code Comments: Precise feedback with gitlab_create_merge_request_discussion
  • Multi-Client Support: Concurrent access for team collaboration
  • Session Management: Robust session handling with automatic recovery
  • Production Ready: Comprehensive logging, monitoring, and error handling

Installation

The easiest way to run the GitLab MCP Server is using the pre-built Docker image:

# Pull the latest image docker pull ghcr.io/atla-digital/mcp-gitlab:latest # Run the container docker run -d -p 3001:3000 --name mcp-gitlab-server ghcr.io/atla-digital/mcp-gitlab:latest

The server will be available at http://localhost:3001/mcp

Option 2: Using Docker Compose

Create a docker-compose.yml file:

services: mcp-gitlab: image: ghcr.io/atla-digital/mcp-gitlab:latest ports: - "3001:3000" restart: unless-stopped

Then run:

docker compose up -d

Option 3: Building from Source

If you want to build from source or contribute to the project:

Prerequisites
  • Node.js (v16 or higher)
  • npm
  • A GitLab account with an API token
Setup
  1. Clone the repository:
git clone https://github.com/atla-digital/mcp-gitlab.git cd mcp-gitlab
  1. Install dependencies:
npm install
  1. Build the server:
npm run build
  1. Install git hooks (optional, but recommended for contributors):
npm run install-hooks

This installs a pre-commit hook that automatically regenerates TOOLS.md when src/utils/tools-data.ts changes.

  1. Deploy the server:
docker compose up --build -d

The server will be available at http://localhost:3001/mcp

Configuration

This server implements Streamable HTTP as the primary MCP transport, which is now natively supported by Claude Code.

The easiest way to add the GitLab MCP server is using the Claude CLI:

# For GitLab.com claude mcp add sm-gitlab http://host.docker.internal:3001/mcp \ --transport http \ --scope user \ -H "X-GitLab-Token: YOUR_GITLAB_API_TOKEN" \ -H "X-GitLab-URL: https://gitlab.com" # For self-hosted GitLab claude mcp add sm-gitlab http://host.docker.internal:3001/mcp \ --transport http \ --scope user \ -H "X-GitLab-Token: YOUR_GITLAB_API_TOKEN" \ -H "X-GitLab-URL: https://your-gitlab-instance.com"
Manual Configuration (Alternative)

Alternatively, you can manually add the following to your MCP settings file (~/.claude.json):

{ "mcpServers": { "sm-gitlab": { "type": "http", "url": "http://host.docker.internal:3001/mcp", "headers": { "X-GitLab-Token": "YOUR_GITLAB_API_TOKEN", "X-GitLab-URL": "https://your-gitlab-instance.com" } } } }
Configuration Details
  • X-GitLab-Token: Your GitLab API token (required)
  • X-GitLab-URL: Your GitLab instance URL (optional, defaults to https://gitlab.com)

Important Notes:

  • The server automatically appends /api/v4 to the GitLab URL if not present
  • Only GitLab API v4 is supported
  • You can generate a token in your GitLab account under Settings > Access Tokens

Example GitLab URLs:

# For GitLab.com -H "X-GitLab-URL: https://gitlab.com" # For self-hosted GitLab -H "X-GitLab-URL: https://your-gitlab-instance.com" # Already includes /api/v4 (also works) -H "X-GitLab-URL: https://gitlab.com/api/v4"
Environment Configuration

The server supports configuration via environment variables with validation and sensible defaults:

# Copy the example configuration cp .env.example .env # Edit with your values nano .env

Available Configuration Options:

VariableDescriptionDefault
PORTServer port3000
NODE_ENVEnvironment (development/production/test)development
LOG_LEVELLogging level (error/warn/info/http/debug)info
SESSION_MAX_AGESession lifetime in milliseconds604800000 (7 days)
SESSION_CLEANUP_INTERVALSession cleanup interval in milliseconds300000 (5 minutes)
AXIOS_TIMEOUTHTTP request timeout in milliseconds30000 (30 seconds)
ENABLE_REQUEST_LOGGINGEnable detailed API request loggingtrue
ENABLE_DETAILED_ERRORSEnable detailed error messagesfalse

Example .env file:

PORT=3000 NODE_ENV=development LOG_LEVEL=info SESSION_MAX_AGE=604800000 SESSION_CLEANUP_INTERVAL=300000 AXIOS_TIMEOUT=30000 ENABLE_REQUEST_LOGGING=true ENABLE_DETAILED_ERRORS=false
Logging & Monitoring

The server features comprehensive structured logging with Winston:

Log Components:

  • API Logger: GitLab API requests and responses
  • Session Logger: Session creation, cleanup, and lifecycle
  • Server Logger: HTTP server events and errors
  • Auth Logger: Authentication and authorization events

Log Formats:

  • Console: Colorized, human-readable format for development
  • Files: JSON format in production (saved to logs/ directory)

Log Level Control: Set the LOG_LEVEL environment variable to control verbosity:

  • error: Only errors
  • warn: Warnings and errors
  • info: General information, warnings, and errors (default)
  • http: HTTP requests/responses plus above
  • debug: Detailed debugging information plus above

Production Logging:

# Set log level for production LOG_LEVEL=warn NODE_ENV=production npm start # View logs in production tail -f logs/combined.log tail -f logs/error.log

Updating to Latest Version

To update to the latest version when using the pre-built Docker image:

# Stop the current container docker stop mcp-gitlab-server docker rm mcp-gitlab-server # Pull the latest image docker pull ghcr.io/atla-digital/mcp-gitlab:latest # Run with the new image docker run -d -p 3001:3000 --name mcp-gitlab-server ghcr.io/atla-digital/mcp-gitlab:latest

Or if using Docker Compose:

docker compose pull docker compose up -d

Available Tools

For a complete list of available tools and their parameters, see TOOLS.md.

Example Usage

Here are examples of how to use these tools with AI assistants that support MCP:

List your projects

Could you list my GitLab projects?

Get information about a specific merge request

Can you show me the details of merge request with ID 123 in the project 'mygroup/myproject'?

Add a comment to a merge request

Please add a comment to merge request 123 in project 'mygroup/myproject' saying "This looks good, but please add more tests."

Add an internal note to a merge request

Add an internal note to merge request 123 in project 'mygroup/myproject' that says "Needs security review before merging." Make sure it's only visible to team members.

Update a merge request title and description

Update the title of merge request 123 in project 'mygroup/myproject' to "Fix login page performance issues" and update the description to include "This PR addresses the slow loading times on the login page by optimizing database queries."

Compare branches

Compare the 'feature-branch' with 'main' in the project 'mygroup/myproject' and show me the differences.

Practical Workflows

Reviewing a Merge Request

1. Show me merge request 123 in project 'mygroup/myproject' 2. Show me the changes for this merge request 3. Add an internal note with my review comments 4. Update the merge request title to better reflect the changes

Project Exploration

1. List all my GitLab projects 2. Show me the details of project 'mygroup/myproject' 3. List all branches in this project 4. Show me the content of the README.md file in the main branch

Available Resources

gitlab://projects

List of GitLab projects accessible with your API token.

Integration with AI Assistants

The GitLab MCP Server integrates with AI assistants that support the Model Context Protocol (MCP).

Capabilities

When connected to an AI assistant, this server enables the assistant to:

  1. View and analyze code: The assistant can fetch file contents, view branch differences, and examine merge request changes for better code understanding.
  2. Provide code reviews: The assistant can analyze merge requests and provide feedback through comments or internal notes.
  3. Manage project workflows: The assistant can update merge request attributes, add comments, and help with repository management tasks.
  4. Explore project structure: The assistant can browse projects, branches, and files to understand the codebase structure.
  5. Configure CI/CD and integrations: The assistant can help set up webhooks, manage CI/CD variables, and configure project integrations.

Getting the Most from AI Assistant Integration

  • Be specific when asking about projects, merge requests, or files
  • Provide project IDs or paths when possible
  • Use the assistant for code review by asking it to analyze specific merge requests
  • Have the assistant help with repository configuration and management tasks
  • Use internal notes for team-only feedback on merge requests

License

MIT

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

mcp-gitlab

  1. Features
    1. Core Repository Features
    2. Project Settings & Integrations
    3. CI/CD Management
    4. User & Group Administration
  2. 🚀 Perfect Match: MCP-Workflow Integration
    1. 🔄 Structured GitLab Operations
    2. 🎯 Workflow-Driven GitLab
    3. 💡 Real-World Example
    4. 🏆 Why This Combination Works
    5. 🔧 This MCP Server Provides
  3. Installation
    1. Option 1: Using Pre-built Docker Image (Recommended)
    2. Option 2: Using Docker Compose
    3. Option 3: Building from Source
    4. Configuration
    5. Updating to Latest Version
  4. Available Tools
    1. Example Usage
      1. List your projects
      2. Get information about a specific merge request
      3. Add a comment to a merge request
      4. Add an internal note to a merge request
      5. Update a merge request title and description
      6. Compare branches
    2. Practical Workflows
      1. Reviewing a Merge Request
      2. Project Exploration
    3. Available Resources
      1. gitlab://projects
    4. Integration with AI Assistants
      1. Capabilities
      2. Getting the Most from AI Assistant Integration
    5. License

      Related MCP Servers

      • GitLab MCP Serverofficial

        modelcontextprotocol
        A
        security
        A
        license
        A
        quality
        MCP Server for the GitLab API, enabling project management, file operations, and more.
        Last updated -
        9
        1,673
        66,043
        MIT License
        • Linux
        • Apple

      • gitlab mcp

        zereight
        A
        security
        A
        license
        A
        quality
        gitlab mcp
        Last updated -
        13
        6,292
        513
        MIT License
        • Linux
        • Apple

      • gitlab-mcp-server

        yoda-digital
        A
        security
        A
        license
        A
        quality
        GitLab MCP Server (with activity tracking and group projects listing features) This server is based on the original GitLab MCP server with Group Projects Listing and Activity Tracking enhancements
        Last updated -
        28
        357
        26
        MIT License

      • GitLab MCP Server

        harshmaur
        -
        security
        A
        license
        -
        quality
        An MCP server that enables communication with GitLab repositories, allowing interaction with GitLab's API to manage projects, issues, and repositories through natural language.
        Last updated -
        6,292
        1
        MIT License

      View all related MCP servers

      New MCP Servers

      MCP directory API

      We provide all the information about MCP servers via our MCP API.

      curl -X GET 'https://glama.ai/api/mcp/v1/servers/atla-digital/mcp-gitlab'

      If you have feedback or need assistance with the MCP directory API, please join our Discord server