49 tools · PAT Auth · Open Source

GitLab MCP Server

Connect your AI assistant to GitLab through the Model Context Protocol. 49 tools, PAT authentication, zero data stored.

28 Read · 21 Write · PAT Auth · Zero Storage
Get Started GitHub

Quick Start

1 Create a Personal Access Token
Go to GitLab Access Tokens and create a new token with the api scope (or read_api for read-only access).
2 Note your GitLab URL (optional)
If you use a self-hosted GitLab instance, note your URL (e.g. https://gitlab.example.com). For gitlab.com users, this step is not needed.
3 Configure your MCP client
Choose your client below and add the configuration. You'll need your PAT as the Authorization: Bearer header value.
See the MCP Client Configuration section below for detailed setup instructions for each client.

MCP Client Configuration

macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Claude Desktop's built-in Custom Connector (Settings → Connectors) does not support custom headers. Use the mcp-remote wrapper instead.
PAT Authentication
json 
{
  "mcpServers": {
    "gitlab": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://mcp-gitlab.flaremity.com/mcp",
        "--header",
        "Authorization: Bearer ${GITLAB_TOKEN}"
      ],
      "env": {
        "GITLAB_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}
Self-hosted GitLab variant
json 
{
  "mcpServers": {
    "gitlab": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://mcp-gitlab.flaremity.com/mcp",
        "--header",
        "Authorization: Bearer ${GITLAB_TOKEN}",
        "--header",
        "X-GitLab-URL: ${GITLAB_URL}"
      ],
      "env": {
        "GITLAB_TOKEN": "<your-personal-access-token>",
        "GITLAB_URL": "https://gitlab.example.com"
      }
    }
  }
}
PAT Authentication
bash 
# Add to current project only (default)
claude mcp add gitlab \
  https://mcp-gitlab.flaremity.com/mcp \
  --transport http \
  --header "Authorization: Bearer <your-personal-access-token>"

# Add globally (available in all projects)
claude mcp add --scope user gitlab \
  https://mcp-gitlab.flaremity.com/mcp \
  --transport http \
  --header "Authorization: Bearer <your-personal-access-token>"
powershell 
# Add to current project only (default)
claude mcp add gitlab `
  https://mcp-gitlab.flaremity.com/mcp `
  --transport http `
  --header "Authorization: Bearer <your-personal-access-token>"

# Add globally (available in all projects)
claude mcp add --scope user gitlab `
  https://mcp-gitlab.flaremity.com/mcp `
  --transport http `
  --header "Authorization: Bearer <your-personal-access-token>"
Self-hosted GitLab variant
bash 
# Add --header for custom GitLab URL
claude mcp add gitlab \
  https://mcp-gitlab.flaremity.com/mcp \
  --transport http \
  --header "Authorization: Bearer <your-personal-access-token>" \
  --header "X-GitLab-URL: https://gitlab.example.com"
Or edit config file directly
json 
{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "url": "https://mcp-gitlab.flaremity.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}
Project .mcp.json (project root, cross-platform)
User ~/.claude.json (macOS/Linux)
User %USERPROFILE%\.claude.json (Windows)
Add via Settings → MCP → Add MCP Server, or edit config file directly.
Global ~/.cursor/mcp.json (macOS/Linux)  |  %USERPROFILE%\.cursor\mcp.json (Windows)
Project .cursor/mcp.json (project root)
PAT Authentication
json 
{
  "mcpServers": {
    "gitlab": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://mcp-gitlab.flaremity.com/mcp",
        "--header",
        "Authorization: Bearer ${GITLAB_TOKEN}"
      ],
      "env": {
        "GITLAB_TOKEN": "<your-personal-access-token>"
      }
    }
  }
}
Self-hosted GitLab variant
json 
{
  "mcpServers": {
    "gitlab": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://mcp-gitlab.flaremity.com/mcp",
        "--header",
        "Authorization: Bearer ${GITLAB_TOKEN}",
        "--header",
        "X-GitLab-URL: ${GITLAB_URL}"
      ],
      "env": {
        "GITLAB_TOKEN": "<your-personal-access-token>",
        "GITLAB_URL": "https://gitlab.example.com"
      }
    }
  }
}
.vscode/mcp.json (cross-platform)
PAT Authentication
json 
{
  "servers": {
    "gitlab": {
      "url": "https://mcp-gitlab.flaremity.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}
Self-hosted GitLab variant
json 
{
  "servers": {
    "gitlab": {
      "url": "https://mcp-gitlab.flaremity.com/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>",
        "X-GitLab-URL": "https://gitlab.example.com"
      }
    }
  }
}
macOS / Linux ~/.codeium/windsurf/mcp_config.json
Windows %USERPROFILE%\.codeium\windsurf\mcp_config.json
PAT Authentication
json 
{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "serverUrl": "https://mcp-gitlab.flaremity.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>"
      }
    }
  }
}
Self-hosted GitLab variant
json 
{
  "mcpServers": {
    "gitlab": {
      "type": "http",
      "serverUrl": "https://mcp-gitlab.flaremity.com/mcp",
      "headers": {
        "Authorization": "Bearer <your-personal-access-token>",
        "X-GitLab-URL": "https://gitlab.example.com"
      }
    }
  }
}

Features

🔧
49 GitLab Tools
Projects, merge requests, pipelines, issues, labels, commits, branches, groups, and more.
🏠
Self-Hosted Support
Works with gitlab.com and self-hosted instances. Set your GitLab URL via the X-GitLab-URL header.
🔐
PAT Authentication
Simple Personal Access Token auth via Bearer header, PRIVATE-TOKEN header, or environment variable.
🛡️
Read-Only Mode
Enable READ_ONLY_MODE to disable all 21 write tools. Perfect for safe, audit-friendly setups.
⚡
Anti-Hanging Design
Fetch timeouts, 5MB response size guards, pipeline log truncation, and response simplification.
☁️
Zero Data Storage
Stateless proxy on Cloudflare Workers. No database, no logs, no data retention.

Tools Catalog

49 tools organized by category

Projects & Repository 11 tools
Projects
get_project Get project details by ID or path Read
list_projects List accessible projects Read
search_repositories Search for repositories by keyword Read
create_repository Create a new project Write
Repository
get_repository_tree List repository file tree Read
get_file_contents Get file content from a repository Read
create_or_update_file Create or update a single file Write
push_files Push multiple files in a single commit Write
Branches
get_branch_diffs Compare two branches Read
create_branch Create a new branch Write
fork_repository Fork a repository Write
Commits 3 tools
Commits
list_commits List commits in a repository Read
get_commit Get a single commit by SHA Read
get_commit_diff Get the diff of a commit Read
Merge Requests 10 tools
Merge Requests
get_merge_request Get merge request details Read
list_merge_requests List merge requests for a project Read
create_merge_request Create a new merge request Write
update_merge_request Update an existing merge request Write
Diffs
get_merge_request_diffs Get merge request diff content Read
list_merge_request_diffs List files changed in a merge request Read
Discussions
mr_discussions Get merge request discussions Read
create_merge_request_note Add a comment to a merge request Write
create_merge_request_thread Create a discussion thread on a merge request Write
update_merge_request_note Update a merge request comment Write
Pipelines & Jobs 8 tools
Pipelines
list_pipelines List pipelines for a project Read
get_pipeline Get pipeline details Read
create_pipeline Trigger a new pipeline Write
retry_pipeline Retry a failed pipeline Write
cancel_pipeline Cancel a running pipeline Write
Jobs
list_pipeline_jobs List jobs in a pipeline Read
get_pipeline_job Get job details Read
get_pipeline_job_output Get job log output Read
Issues & Notes 7 tools
Issues
get_issue Get issue details Read
list_issues List issues for a project Read
create_issue Create a new issue Write
update_issue Update an existing issue Write
delete_issue Delete an issue Write
Notes
create_note Create a note on a merge request Write
create_issue_note Add a comment to an issue Write
Labels 5 tools
Labels
list_labels List project labels Read
get_label Get label details Read
create_label Create a new label Write
update_label Update a label Write
delete_label Delete a label Write
Users 1 tool
Users
get_users Search for GitLab users Read
Groups & Namespaces 4 tools
Groups
list_namespaces List available namespaces Read
get_namespace Get namespace details Read
verify_namespace Verify if a namespace exists Read
list_group_projects List projects in a group Read

FAQ

What PAT scopes do I need?
For full access (read + write), create a token with the api scope. For read-only access, use read_api. You can also combine this with the server's READ_ONLY_MODE for an extra layer of safety.
Does this work with self-hosted GitLab?
Yes. Add the X-GitLab-URL header with your instance URL (e.g. https://gitlab.example.com) to your MCP client configuration. The server defaults to gitlab.com if no custom URL is provided.
What is Read-Only Mode?
Setting READ_ONLY_MODE=true in the server's environment disables all 21 write tools. Only the 28 read tools will be available. This is useful for auditing, demos, or when you want to ensure no accidental modifications are made.
Where is my data stored?
Nowhere. This server is a stateless proxy running on Cloudflare Workers. It does not store any of your GitLab data, credentials, or API responses. Each request is processed and immediately discarded. No database, no logs, no KV storage.
Can I self-host this?
Yes. Clone the repository, run bun install, and deploy to your own Cloudflare Workers account with bun run deploy. Set your GitLab token via wrangler secret put GITLAB_TOKEN. See the GitHub repository for full instructions.