GitLab MCP Server

A comprehensive Model Context Protocol (MCP) server for GitLab API integration, providing 75 GitLab tools with advanced performance optimization for coding agents.

Quick Start

1. Get your GitLab token:

• Go to GitLab → User Settings → Access Tokens → Create with api scope

2. Add to Claude Desktop config:

{
  "gitlab": {
    "command": "npx",
    "args": ["@haleyio/mcp-servers-gitlab"],
    "env": {
      "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token-here"
    }
  }
}

3. Start Claude Desktop - GitLab tools will be available immediately.

Tool Categories

75 tools organized across 10 categories:

• Repository (7 tools): File operations, search, create/update files
• Branches (6 tools): Branch management and protection
• Issues (13 tools): Issue tracking, comments, time tracking
• Merge Requests (18 tools): Complete MR lifecycle management
• Pipelines (7 tools): CI/CD pipeline operations
• Jobs (8 tools): Job control and monitoring
• Variables (5 tools): CI/CD environment variables
• Project Management (8 tools): Milestones and labels
• CI Configuration (1 tool): YAML validation
• Artifacts (2 tools): Download and manage job artifacts

Complete Tool Reference

Repository (7 tools)

search_repositories create_repository fork_repository delete_repository get_file_contents create_or_update_file push_files

Branches (6 tools)

create_branch get_branches get_branch delete_branch protect_branch unprotect_branch

Issues (13 tools)

create_issue get_issues get_issue update_issue delete_issue get_issue_notes create_issue_note update_issue_note delete_issue_note add_time_spent get_time_stats reset_time_spent set_time_estimate

Merge Requests (18 tools)

create_merge_request get_merge_requests get_merge_request update_merge_request merge_merge_request approve_merge_request unapprove_merge_request get_merge_request_approvals get_merge_request_commits get_merge_request_changes rebase_merge_request close_merge_request reopen_merge_request delete_merge_request get_merge_request_notes create_merge_request_note update_merge_request_note delete_merge_request_note

Pipelines (7 tools)

get_pipelines get_pipeline create_pipeline retry_pipeline cancel_pipeline delete_pipeline get_latest_pipeline

Jobs (8 tools)

get_jobs get_pipeline_jobs get_job get_job_log cancel_job retry_job play_job erase_job

Variables (5 tools)

get_variables get_variable create_variable update_variable delete_variable

Project Management (8 tools)

create_milestone get_milestones update_milestone delete_milestone create_label get_labels update_label delete_label

CI Configuration (1 tool)

validate_ci_config

Artifacts (2 tools)

get_job_artifacts_list download_job_artifact

Performance Optimization

Key differentiator: Up to 95% payload reduction for faster coding agent responses.

Standard Setup (Recommended)

{
  "gitlab": {
    "command": "npx",
    "args": ["@haleyio/mcp-servers-gitlab"],
    "env": {
      "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token"
    }
  }
}

High Performance (Tool-Specific Filtering)

{
  "gitlab": {
    "command": "npx",
    "args": ["@haleyio/mcp-servers-gitlab"],
    "env": {
      "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token",
      "OPTIMIZATION_LEVEL": "minimal",
      "ENABLED_CATEGORIES": "repository:get_file_contents|create_or_update_file"
    }
  }
}

Safety-First Setup (Blocklist Dangerous Operations)

{
  "gitlab-safe": {
    "command": "npx",
    "args": ["@haleyio/mcp-servers-gitlab"],
    "env": {
      "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token",
      "DISABLED_CATEGORIES": "repository:delete_repository|fork_repository,project_mgmt:delete_milestone|delete_label"
    }
  }
}

Performance Results

• File Operations Only: 95% reduction (ENABLED_CATEGORIES="repository:get_file_contents")
• Development Workflow: 60% reduction (ENABLED_CATEGORIES="repository,branches,merge_requests")
• Issue Management: 80% reduction (ENABLED_CATEGORIES="issues")
• Schema Optimization: 30% reduction (OPTIMIZATION_LEVEL="minimal")

Essential Commands

npm run build         # Compile TypeScript
npm test             # Run all tests (sub-5 second execution)
npm run health-check # Validate server startup and performance

Environment Variables

• GITLAB_PERSONAL_ACCESS_TOKEN (required) - GitLab API token with api scope
• GITLAB_API_URL (optional) - For self-hosted GitLab instances
• OPTIMIZATION_LEVEL (optional) - minimal|standard|verbose (default: standard)
• ENABLED_CATEGORIES (optional) - Allowlist for tool filtering (performance optimization)
• DISABLED_CATEGORIES (optional) - Blocklist for tool filtering (applied after ENABLED_CATEGORIES)

Tool Filtering Examples

# Allowlist: Category-level filtering
ENABLED_CATEGORIES="repository,issues,merge_requests"

# Allowlist: Tool-specific filtering (maximum performance)
ENABLED_CATEGORIES="repository:get_file_contents|create_or_update_file"

# Allowlist: Mixed filtering
ENABLED_CATEGORIES="repository:get_file_contents,branches,issues:create_issue"

# Blocklist: Remove dangerous operations
DISABLED_CATEGORIES="repository:delete_repository|fork_repository"

# Blocklist: Remove entire categories
DISABLED_CATEGORIES="branches,pipelines"

# Combined: Enable specific tools, then remove some
ENABLED_CATEGORIES="repository,issues"
DISABLED_CATEGORIES="repository:delete_repository,issues:delete_issue"

# Blocklist: Mixed syntax
DISABLED_CATEGORIES="branches,repository:delete_repository"

Troubleshooting

No tools available?

• Check token in Claude config env section

401 Unauthorized?

• Regenerate GitLab token with api scope

Performance issues?

• Use tool filtering: ENABLED_CATEGORIES="repository" (92% reduction)
• Combine with optimization: OPTIMIZATION_LEVEL="minimal"

Need to block specific operations?

• Use blocklist: DISABLED_CATEGORIES="repository:delete_repository"
• Block entire categories: DISABLED_CATEGORIES="branches,pipelines"
• Combined filtering: Both ENABLED_CATEGORIES and DISABLED_CATEGORIES (disabled takes precedence)

Invalid categories/tools warnings?

• Check spelling against valid categories: repository, branches, issues, merge_requests, pipelines, jobs, variables, project_mgmt, ci_config, artifacts
• Use exact tool names (warnings provide suggestions)

Timeouts with large content?

{
  "env": {
    "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token",
    "GITLAB_API_TIMEOUT_EXTENDED": "180000"
  }
}

Self-hosted GitLab?

{
  "env": {
    "GITLAB_API_URL": "https://your-gitlab.com/api/v4"
  }
}

Testing & Quality

• Sub-5 second test execution with complete mock-based testing
• Contract validation system prevents mock drift from real GitLab API
• Coverage thresholds: 40%/25%/56%/40% (lines/functions/branches/statements)
• Zero setup required - no tokens or network access needed for testing

npm test                           # All tests
npm run test:coverage             # With coverage report
npm run validate:contracts:smoke  # Mock integrity check

Installation Options

NPX (Recommended)

npx @haleyio/mcp-servers-gitlab

Local Development

git clone https://git.haley.io/john/mcp-server-gitlab.git
cd mcp-server-gitlab
npm install && npm run build

License

MIT License - see LICENSE file for details.