GitLab MCP Server

Token-optimized Model Context Protocol server for self-hosted GitLab instances, designed for Claude Code.

Features

• Multi-profile PAT management — switch between multiple GitLab instances

• Compact text responses — minimal token usage for LLM context

• Project caching — avoids redundant API calls (2min TTL)

• Full GitLab workflow — issues, merge requests, pipelines, notes

• Env or config-file auth — flexible credential management

Related MCP server: GitLab MCP Server

Setup

1. Install dependencies

bun install

2. Get a GitLab Personal Access Token

1. Go to your GitLab instance → Settings → Access Tokens

2. Create a token with scopes: api, read_user

3. Configure

Option A: Environment variables

export GITLAB_BASE_URL="https://gitlab.example.com"
export GITLAB_TOKEN="your-personal-access-token"
export GITLAB_DEFAULT_PROJECT="group/subgroup/repo"  # optional

Option B: Use the set_gitlab_pat tool at runtime — profiles are stored in ~/.config/gitlab-mcp-server/config.json with 0600 permissions.

4. Add to Claude Code

Add to your ~/.claude/settings.json or project .claude/settings.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "bun",
      "args": ["run", "/path/to/gitlab-mcp-server/index.ts"],
      "env": {
        "GITLAB_BASE_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "your-personal-access-token",
        "GITLAB_DEFAULT_PROJECT": "group/subgroup/repo"
      }
    }
  }
}

Available Tools

Profile Management

Projects

Issues

Merge Requests

Pipelines

Multi-Instance Support

All tools use the active profile. Switch between GitLab instances:

# Save profiles
set_gitlab_pat(name: "work", baseUrl: "https://gitlab.company.com", token: "...")
set_gitlab_pat(name: "oss", baseUrl: "https://gitlab.com", token: "...")

# Switch
use_gitlab_profile(name: "work")

Projects can be referenced by ID or path:

projectId: "123"
projectPath: "group/subgroup/repo"

If defaultProject is set in the profile, it's used when neither is provided.

License

MIT