Skip to main content

GitLab MCP Server

Create a powerful Model Context Protocol (MCP) server for GitLab in minutes with our AI Gateway. This guide walks you through setting up seamless DevOps integration with enterprise-grade security and instant OAuth authentication.

About GitLab API​

GitLab is a complete DevOps platform delivered as a single application, providing source code management, CI/CD pipelines, security scanning, and more. The GitLab API enables comprehensive automation across the entire software development lifecycle.

Key Capabilities​

  • Source Code Management: Git repositories, branches, and merge requests
  • CI/CD Pipelines: Automated builds, tests, and deployments
  • Issue Tracking: Project management and bug tracking
  • Code Review: Merge request reviews and approvals
  • Container Registry: Docker image management
  • Security Scanning: SAST, DAST, dependency scanning
  • Wiki & Documentation: Project documentation
  • Package Registry: Package management for multiple formats

API Features​

  • REST API v4: Comprehensive DevOps operations
  • GraphQL API: Flexible data queries
  • Webhooks: Real-time event notifications
  • Personal Access Tokens: Secure authentication
  • OAuth 2.0: Third-party integrations
  • Rate Limiting: 600 requests/minute (authenticated)
  • Pagination: Efficient data retrieval
  • Job Artifacts: Build output access

What You Can Do with GitLab MCP Server​

The MCP server transforms GitLab's API into a natural language interface, enabling AI agents to:

Repository Management​

  • Project Operations

    • "Create new repository for microservice project"
    • "Import repository from GitHub"
    • "Archive old projects from last year"
    • "Transfer project to different group"

  • Branch Management

    • "Create feature branch from main"
    • "List all active feature branches"
    • "Delete merged branches older than 30 days"
    • "Protect main branch from direct pushes"

  • File Operations

    • "Update README.md with new documentation"
    • "Create .gitignore for Node.js project"
    • "Get file contents from specific commit"
    • "Search for files containing specific text"

Merge Request Workflow​

  • MR Creation

    • "Create merge request from feature to main"
    • "Set reviewers for critical changes"
    • "Add description with JIRA ticket link"
    • "Mark merge request as draft"

  • Code Review

    • "Show all merge requests awaiting review"
    • "Add inline comments to code changes"
    • "Approve merge request after review"
    • "Request changes with specific feedback"

  • MR Management

    • "Merge approved requests with squash"
    • "Rebase merge request on target branch"
    • "Close stale merge requests"
    • "Cherry-pick commits to release branch"

CI/CD Pipeline Management​

  • Pipeline Operations

    • "Trigger pipeline for production deployment"
    • "Show failed pipelines from last 24 hours"
    • "Retry failed pipeline jobs"
    • "Cancel running pipeline"

  • Job Management

    • "Get logs from failed test job"
    • "Download artifacts from build job"
    • "Restart specific job in pipeline"
    • "View job trace in real-time"

  • Pipeline Configuration

    • "Update .gitlab-ci.yml with new stage"
    • "Add environment variables to pipeline"
    • "Configure deployment to staging"
    • "Set up scheduled pipeline runs"

Issue & Project Management​

  • Issue Operations

    • "Create bug report for login issue"
    • "Assign issue to developer"
    • "Add labels for priority and type"
    • "Move issue to different milestone"

  • Issue Tracking

    • "Show all open issues for current sprint"
    • "Find issues assigned to me"
    • "List bugs marked as critical"
    • "Search issues by keyword"

  • Milestone Management

    • "Create milestone for v2.0 release"
    • "Show progress on current milestone"
    • "Move incomplete issues to next milestone"
    • "Generate burndown chart"

Security & Compliance​

  • Security Scanning

    • "Run SAST scan on feature branch"
    • "Show vulnerabilities found in project"
    • "Get dependency scanning results"
    • "Check license compliance"

  • Access Management

    • "Add user to project with developer role"
    • "Remove external collaborator access"
    • "List users with maintainer permissions"
    • "Audit user activities in project"

  • Protected Resources

    • "Protect production branch"
    • "Set up push rules for main branch"
    • "Configure protected tags"
    • "Manage deploy keys"

Package & Container Registry​

  • Package Management

    • "Publish npm package to registry"
    • "List all packages in project"
    • "Delete old package versions"
    • "Set package visibility"

  • Container Registry

    • "List Docker images in registry"
    • "Delete untagged images"
    • "Get image manifest"
    • "Set retention policy"

Analytics & Insights​

  • Code Analytics

    • "Show commit activity over time"
    • "Get contributor statistics"
    • "Analyze code coverage trends"
    • "Track merge request metrics"

  • Pipeline Analytics

    • "Calculate pipeline success rate"
    • "Show average pipeline duration"
    • "Identify bottleneck stages"
    • "Track deployment frequency"

  • Project Insights

    • "Generate activity report"
    • "Show cycle time metrics"
    • "Track issue resolution time"
    • "Monitor code review turnaround"

Prerequisites​

  • Access to Cequence AI Gateway
  • GitLab account (gitlab.com or self-hosted)
  • API access permissions
  • Personal Access Token or OAuth app

Step 1: Create GitLab OAuth Application​

1.1 Access GitLab Settings​

For GitLab.com:

  1. Go to gitlab.com
  2. Navigate to Settings Applications

1.2 Create New Application​

  1. Click New Application
  2. Fill in details:
    • Name: "AI Gateway GitLab MCP"
    • Redirect URI: 
      https://auth.aigateway.cequence.ai/v1/outbound/oauth/callback
    • Confidential: Yes
    • Scopes: Select based on needs (see scopes section)

1.3 Save Credentials​

  1. Click Save application
  2. Copy Application ID (Client ID)
  3. Copy Secret (Client Secret)

Step 2-4: Standard Setup​

Follow standard steps to access AI Gateway, find GitLab API, and create MCP server.

Step 5: Configure API Endpoints​

  1. Base URL:
    • GitLab.com: https://gitlab.com/api/v4
    • Self-hosted: https://your-gitlab.com/api/v4
  2. Select endpoints to expose
  3. Click Next

Step 6: MCP Server Configuration​

  1. Name: "GitLab DevOps Platform"
  2. Description: "Source control and CI/CD automation"
  3. Configure production mode
  4. Click Next

Step 7: Configure Authentication​

  1. Authentication Type: OAuth 2.0
  2. Authorization URL: 
    https://gitlab.com/oauth/authorize
  3. Token URL: 
    https://gitlab.com/oauth/token
  4. Enter Application ID and Secret
  5. Select required scopes

Available GitLab OAuth Scopes​

Repository Access​

  • read_repository

    • Clone and pull repositories
    • View files and commits
    • Access branches and tags
    • Read merge requests

  • write_repository

    • Push to repositories
    • Create branches and tags
    • Modify files
    • Delete branches

API Access​

  • api

    • Full API access
    • All read/write operations
    • Administrative functions
    • Complete control

  • read_api

    • Read-only API access
    • View all resources
    • No modifications
    • Safe for reporting

User Access​

  • read_user

    • Read user profile
    • View user activities
    • Access preferences
    • See group memberships

  • sudo

    • Perform actions as other users
    • Administrative operations
    • Requires admin privileges
    • Use with caution

Additional Scopes​

  • read_registry / write_registry

    • Container registry access
    • Package registry operations
    • Image management
    • Package publishing

  • openid / profile / email

    • OpenID Connect scopes
    • User authentication
    • Profile information
    • Email access

For Development Workflows:

api
read_user

For CI/CD Automation:

api
read_registry
write_registry

For Read-Only Access:

read_api
read_user
read_repository
read_registry

Step 8-10: Complete Setup​

Configure security, choose deployment, and deploy.

Using Your GitLab MCP Server​

With Standard MCP Clients like Claude Desktop, Cursor, Windsurf​

  1. Open Claude Desktop settings
  2. Add your MCP server: 
    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y",
            "@cequenceai/mcp-remote",
            "your-mcp-url"
          ]
        }
      }
    }

With Cursor IDE​

  1. Open Cursor IDE and go to Settings (Cmd/Ctrl + ,).
  2. Navigate to Tools & Integrations and click New MCP Server.
  3. Add your MCP server: 
    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y",
            "@cequenceai/mcp-remote",
            "your-mcp-url"
          ]
        }
      }
    }

With Windsurf IDE​

  1. Open Windsurf IDE and click Windsurf - Settings (bottom right) or press Cmd/Ctrl + Shift + P.
  2. Type Open Windsurf Settings and select Advanced → Cascade.
  3. Click Add Server → Add custom server +.
  4. Add your MCP server: 
    {
      "mcpServers": {
        "GitLab": {
          "command": "npx",
          "args": [
            "-y",
            "@cequenceai/mcp-remote",
            "your-mcp-url"
          ],
          "disabled": false,
          "alwaysAllow": []
        }
      }
    }

Natural Language Commands​

  • "Create merge request from feature/login to main"
  • "Show all failed pipelines from today"
  • "List open issues labeled as 'bug'"
  • "Trigger deployment pipeline for production"
  • "Get code coverage report for main branch"

Common Use Cases​

Development Workflows​

  • Feature branch management
  • Code review automation
  • Merge conflict resolution
  • Release tagging

CI/CD Automation​

  • Pipeline orchestration
  • Deployment automation
  • Test result analysis
  • Artifact management

Project Management​

  • Issue triage
  • Sprint planning
  • Milestone tracking
  • Time tracking

Security & Compliance​

  • Vulnerability scanning
  • License compliance
  • Access auditing
  • Security policy enforcement

Security Best Practices​

  1. Access Control:

    • Use minimal scopes
    • Rotate tokens regularly
    • Implement IP restrictions
    • Audit API usage

  2. Repository Security:

    • Protect critical branches
    • Enforce merge request reviews
    • Sign commits
    • Scan for secrets

  3. CI/CD Security:

    • Secure variables
    • Limit runner access
    • Verify artifacts
    • Monitor deployments

Troubleshooting​

Common Issues​

  1. Authentication Errors

    • Verify OAuth credentials
    • Check token expiration
    • Validate redirect URI
    • Review granted scopes

  2. Permission Denied

    • Check project permissions
    • Verify group membership
    • Review protected branch settings
    • Confirm API access level

  3. Rate Limiting

    • Monitor API usage
    • Implement caching
    • Use pagination properly
    • Consider self-hosted instance

Getting Help​