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

Recommended Scope Combinations

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

{
  "servers": {
    "gitlab": {
      "url": "your-mcp-server-url",
      "auth": {
        "type": "oauth2",
        "client_id": "your-application-id"
      }
    }
  }
}

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"

API Integration Example

// Initialize MCP client
const mcpClient = new MCPClient({
  serverUrl: 'your-mcp-server-url',
  auth: {
    type: 'oauth2',
    token: 'access-token'
  }
});

// Create project
const project = await mcpClient.gitlab.projects.create({
  name: 'new-microservice',
  description: 'Authentication microservice',
  visibility: 'private',
  initialize_with_readme: true,
  default_branch: 'main'
});

// Create merge request
const mr = await mcpClient.gitlab.mergeRequests.create({
  id: project.id,
  source_branch: 'feature/oauth-integration',
  target_branch: 'main',
  title: 'Add OAuth 2.0 support',
  description: 'Implements OAuth 2.0 authentication flow\n\nCloses #42',
  assignee_id: 123,
  reviewer_ids: [456, 789],
  labels: ['enhancement', 'security']
});

// Trigger pipeline
const pipeline = await mcpClient.gitlab.pipelines.create({
  id: project.id,
  ref: 'main',
  variables: [
    { key: 'DEPLOY_ENV', value: 'production' },
    { key: 'SKIP_TESTS', value: 'false' }
  ]
});

// Create issue
const issue = await mcpClient.gitlab.issues.create({
  id: project.id,
  title: 'Implement rate limiting',
  description: 'Add rate limiting to prevent API abuse',
  assignee_ids: [123],
  labels: ['enhancement', 'security', 'backend'],
  milestone_id: 5,
  due_date: '2025-03-01'
});

// Get pipeline status
const pipelineStatus = await mcpClient.gitlab.pipelines.get({
  id: project.id,
  pipeline_id: pipeline.id
});

// Download job artifacts
const artifacts = await mcpClient.gitlab.jobs.downloadArtifacts({
  id: project.id,
  job_id: pipelineStatus.jobs[0].id
});

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

• Documentation: AI Gateway Docs
• Support: support@cequence.ai
• GitLab Docs: docs.gitlab.com
• API Reference: GitLab API Docs

---