npm package: @haleyio/mcp-servers-gitlab
Description: MCP server for GitLab integration - provides tools for repository management, issue tracking, and merge request operations
Author: John Haley
Latest version: 3.0.0

# GitLab MCP Server

[![Coverage](https://git.haley.io/john/mcp-server-gitlab/-/jobs/artifacts/main/raw/coverage/badge.svg?job=test:coverage)](https://git.haley.io/john/mcp-server-gitlab/-/jobs/artifacts/main/file/coverage/index.html?job=test:coverage)

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:**
```json
{
  "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)
```json
{
  "gitlab": {
    "command": "npx",
    "args": ["@haleyio/mcp-servers-gitlab"],
    "env": {
      "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token"
    }
  }
}
```

### High Performance (Tool-Specific Filtering)
```json
{
  "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)
```json
{
  "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

```bash
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
```bash
# 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?**
```json
{
  "env": {
    "GITLAB_PERSONAL_ACCESS_TOKEN": "your-token",
    "GITLAB_API_TIMEOUT_EXTENDED": "180000"
  }
}
```

**Self-hosted GitLab?**
```json
{
  "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

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

## Installation Options

### NPX (Recommended)
```bash
npx @haleyio/mcp-servers-gitlab
```

### Local Development
```bash
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.