Which integrations are available for this server?

Provides comprehensive tools for GitLab: manage projects, merge requests, issues, pipelines, wikis, milestones, releases, labels, commits, branches, and file management.

How do I use gitlab-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@gitlab-mcp list merge requests assigned to me" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

gitlab-mcp

by mcpland

Overview Schema Related Servers Score Discussions

TypeScript

Hybrid

gitlab-mcp

Node CI npm license

A production-ready MCP server for GitLab. Provides 80+ tools that let AI assistants read and manage GitLab projects, merge requests, issues, pipelines, wikis, releases, and more through a unified, policy-controlled interface.

Highlights

Comprehensive GitLab coverage — projects, merge requests (with code-context analysis), issues, pipelines, wikis, milestones, releases, labels, commits, branches, GraphQL, and file management
Multiple transports — stdio for local CLI usage, Streamable HTTP for remote deployments, optional SSE
Flexible authentication — personal access tokens, OAuth 2.0 PKCE, external token scripts, token files, cookie-based auth, and per-request remote authorization
Policy engine — read-only mode, tool allowlist/denylist, feature toggles, and project-scoped restrictions
Enterprise networking — HTTP/HTTPS proxy, custom CA certificates, Cloudflare bypass, multi-instance API rotation
Output control — JSON, compact JSON, or YAML formatting with configurable response size limits

Related MCP server: GitLab MCP Server

Usage

Supported clients

Claude Desktop, Claude Code, VS Code, GitHub Copilot Chat (VS Code), Cursor, JetBrains AI Assistant, GitLab Duo, and any MCP client that supports stdio or streamable HTTP.

Current client format references:

Authentication methods

The server supports three auth patterns:

Personal Access Token (PAT)
OAuth 2.0 PKCE (recommended for local interactive use)
Remote per-request auth (REMOTE_AUTHORIZATION=true, HTTP mode)

OAuth2 setup (stdio, recommended for local interactive use)

Create a GitLab OAuth application in Settings -> Applications.
Set redirect URI to http://127.0.0.1:8765/callback (or your custom callback).
Set scope to api.
Copy the Application ID as GITLAB_OAUTH_CLIENT_ID.

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

If your OAuth app is confidential, also set GITLAB_OAUTH_CLIENT_SECRET.

Personal Access Token setup (stdio)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "gitlab-mcp@latest"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_ALLOWED_PROJECT_IDS": "",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}

VS Code `.vscode/mcp.json` examples

PAT with secure prompt input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab_token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}

OAuth (confidential app) with secure prompt input:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab_oauth_secret",
      "description": "GitLab OAuth Client Secret",
      "password": true
    }
  ],
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "${input:gitlab_oauth_secret}",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8765/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GitHub Copilot Chat in VS Code uses the same .vscode/mcp.json format.

Claude Desktop / Claude Code / Cursor

Claude Desktop reads claude_desktop_config.json. Claude Code supports project-level .mcp.json and claude mcp add-json. Cursor uses .cursor/mcp.json.

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GitLab Duo (`~/.gitlab/duo/mcp.json`)

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": ["/absolute/path/to/gitlab-mcp/dist/index.js"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  },
  "approvedTools": ["gitlab_get_project", "gitlab_list_merge_requests"]
}

JetBrains AI Assistant

JetBrains can import an existing MCP JSON config or register the server manually. Use stdio command node /absolute/path/to/gitlab-mcp/dist/index.js, or HTTP endpoint http://127.0.0.1:3333/mcp with required headers.

Remote authorization (multi-user HTTP)

Start server:

REMOTE_AUTHORIZATION=true \
HTTP_HOST=0.0.0.0 \
HTTP_PORT=3333 \
node dist/http.js

Client config:

{
  "mcpServers": {
    "gitlab": {
      "url": "http://127.0.0.1:3333/mcp",
      "headers": {
        "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Dynamic per-request API URL:

REMOTE_AUTHORIZATION=true \
ENABLE_DYNAMIC_API_URL=true \
HTTP_HOST=0.0.0.0 \
HTTP_PORT=3333 \
node dist/http.js

Add header in client requests:

{
  "headers": {
    "Authorization": "Bearer glpat-xxxxxxxxxxxxxxxxxxxx",
    "X-GitLab-API-URL": "https://gitlab.example.com/api/v4"
  }
}

Remote auth behavior matrix:

Server Mode	Required Request Headers	Token Fallback Chain
`REMOTE_AUTHORIZATION=false` on local HTTP bind only	none	enabled
`REMOTE_AUTHORIZATION=true`	`Authorization: Bearer <token>`, `Private-Token: <token>`, or `Job-Token: <token>`	disabled
`REMOTE_AUTHORIZATION=true` + `ENABLE_DYNAMIC_API_URL=true`	`Authorization`, `Private-Token`, or `Job-Token`, and `X-GitLab-API-URL: https://host/api/v4`	disabled

When HTTP_HOST is not 127.0.0.1, localhost, or ::1, HTTP startup rejects server-side GITLAB_PERSONAL_ACCESS_TOKEN or GITLAB_JOB_TOKEN unless REMOTE_AUTHORIZATION=true.

Docker

For containerized deployments, PAT or remote auth is recommended. OAuth interactive callback flow is usually less convenient in containers.

docker compose up --build -d

or:

docker build -t gitlab-mcp .

docker run -d \
  --name gitlab-mcp \
  -p 3333:3333 \
  -e GITLAB_API_URL=https://gitlab.com/api/v4 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
  gitlab-mcp

Compatibility notes

GITLAB_PROJECT_ID is not a supported environment variable in this repository.
To set an effective default project, use GITLAB_ALLOWED_PROJECT_IDS with one project ID, or pass project_id in tool arguments.
CLI argument overrides such as --token or --api-url are not implemented (--env-file is supported).
JSON config files do not support comments (//).

MCP Server Configuration

HTTP server

pnpm install
cp .env.example .env
pnpm build

# stdio (local MCP)
pnpm start

# streamable HTTP server (http://127.0.0.1:3333/mcp)
pnpm start:http

# optional: load a specific env file
pnpm start -- --env-file .env.local
pnpm start:http -- --env-file .env.local

Transport and entrypoint

Transport	Entry Point	Endpoint	Best For
stdio	`node dist/index.js`	stdin/stdout	Local single-user MCP clients
Streamable HTTP	`node dist/http.js`	`POST/GET/DELETE /mcp`	Remote/shared deployments
SSE (legacy)	`node dist/http.js`	`GET /sse`, `POST /messages`	Legacy SSE-only clients (`SSE=true`)
Health	`node dist/http.js`	`GET /healthz`	Liveness/readiness checks

SSE=true is not compatible with REMOTE_AUTHORIZATION=true.

Tool Categories

Tools are organized into these categories. All GitLab tools use the gitlab_ prefix, except health_check.

Category	Examples	Count
Projects	`get_project`, `list_projects`, `create_repository`, `fork_repository`	8
Repository	`get_repository_tree`, `get_file_contents`, `push_files`, `create_branch`	7
Merge Requests	`list_merge_requests`, `get_merge_request_conflicts`, `merge_merge_request`	13
MR Code Context	`get_merge_request_code_context` (advanced code review)	1
MR Discussions	`list_merge_request_discussions`, `create_merge_request_thread`	7
MR Notes	`list_merge_request_notes`, `create_merge_request_note`	7
Draft Notes	`list_draft_notes`, `create_draft_note`, `bulk_publish_draft_notes`	7
Issues	`list_issues`, `create_issue`, `update_issue`, issue links	13
Pipelines	`list_pipelines`, `list_deployments`, `get_job_artifact_file_inline`	20
Commits	`list_commits`, `get_commit`, `get_commit_diff`	3
Labels	`list_labels`, `create_label`, `update_label`	5
Milestones	`list_milestones`, `create_milestone`, burndown events	10
Releases	`list_releases`, `create_release`, `download_release_asset`	7
Wiki	`list_wiki_pages`, `create_wiki_page`, `update_wiki_page`	5
Uploads	`upload_markdown`, `download_attachment`	2
GraphQL	`execute_graphql_query`, `execute_graphql_mutation`	3
Users & Groups	`get_users`, `list_namespaces`, `list_events`	6
Health	`health_check`	1

See docs/tools.md for the complete reference.

Policy & Security

The policy engine controls which tools are available at registration time:

# Read-only mode — disables write/delete/admin capabilities
GITLAB_READ_ONLY_MODE=true

# Disable specific capability classes without going fully read-only
GITLAB_DISABLED_CAPABILITIES=delete,graphql

# Only expose specific tools (supports with or without gitlab_ prefix)
GITLAB_ALLOWED_TOOLS=get_project,list_merge_requests,get_merge_request

# Block tools by regex pattern
GITLAB_DENIED_TOOLS_REGEX=^gitlab_(delete|create)_

# Restrict to specific projects
GITLAB_ALLOWED_PROJECT_IDS=123,456,789

# Keep GraphQL tools enabled in project-scoped mode (disabled by default)
GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE=true

# Disable feature groups
USE_PIPELINE=false
USE_GITLAB_WIKI=false

Unsafe or invalid GITLAB_DENIED_TOOLS_REGEX patterns fail startup.

Configuration

All configuration is done through environment variables. Key settings:

For file-based loading, .env is loaded by default. You can override it with:

node dist/index.js --env-file .env.local
node dist/http.js --env-file=.env.production

Area	Variable	Default	Description
GitLab API	`GITLAB_API_URL`	`https://gitlab.com/api/v4`	Base API URL. Supports comma-separated multi-instance URLs.
GitLab API	`GITLAB_PERSONAL_ACCESS_TOKEN`	—	Static default token used when `REMOTE_AUTHORIZATION=false`.
GitLab API	`GITLAB_JOB_TOKEN`	—	Static CI job token fallback when no personal access token is configured.
Remote Auth	`REMOTE_AUTHORIZATION`	`false`	Require per-request token headers in HTTP mode (disables fallback token chain).
Remote Auth	`ENABLE_DYNAMIC_API_URL`	`false`	Require `X-GitLab-API-URL` per request. Requires `REMOTE_AUTHORIZATION=true`.
Remote Auth	`GITLAB_MCP_OAUTH`	`false`	Enable MCP OAuth discovery/proxy endpoints for HTTP mode. Requires `MCP_SERVER_URL`.
HTTP Server	`HTTP_HOST`	`127.0.0.1`	HTTP bind host (`0.0.0.0` for external access).
HTTP Server	`HTTP_PORT`	`3333`	HTTP server port.
HTTP Server	`MCP_SERVER_URL`	—	Public base URL used when HTTP download tools return proxy URLs.
HTTP Server	`HTTP_JSON_ONLY`	`false`	Force JSON-only responses (no streaming framing).
HTTP Server	`SSE`	`false`	Enable legacy SSE endpoints (`/sse`, `/messages`). Not compatible with remote auth.
Sessions	`SESSION_TIMEOUT_SECONDS`	`3600`	Idle session timeout in HTTP mode.
Sessions	`OAUTH_STATELESS_MODE`	`false`	Use stateless Streamable HTTP transports; clients must send auth on every request.
Sessions	`MAX_SESSIONS`	`1000`	Maximum concurrent sessions (`503` when reached).
Sessions	`MAX_REQUESTS_PER_MINUTE`	`300`	Per-session rate limit (`429` when exceeded).
Policy	`GITLAB_READ_ONLY_MODE`	`false`	Disable tools that require `write`, `delete`, or `admin` capabilities.
Policy	`GITLAB_ALLOWED_PROJECT_IDS`	—	Restrict access to specific GitLab project IDs.
Policy	`GITLAB_ALLOWED_TOOLS`	—	Tool allowlist (supports names with or without `gitlab_` prefix).
Policy	`GITLAB_DISABLED_CAPABILITIES`	—	Capability denylist. Valid values: `read`, `write`, `delete`, `admin`, `graphql`.
Policy	`GITLAB_DENIED_TOOLS_REGEX`	—	Regex denylist for tool names.
Policy	`GITLAB_ALLOW_GRAPHQL_WITH_PROJECT_SCOPE`	`false`	Keep GraphQL tools enabled when project scope restriction is active.
Auth Extensions	`GITLAB_USE_OAUTH`	`false`	Enable OAuth 2.0 PKCE flow.
Auth Extensions	`GITLAB_OAUTH_SCOPES`	mode-dependent	OAuth scopes advertised/requested by local OAuth and MCP OAuth.
Auth Extensions	`GITLAB_TOKEN_SCRIPT`	—	Resolve token from an external script.
Auth Extensions	`GITLAB_TOKEN_FILE`	—	Resolve token from a local file.
Auth Extensions	`GITLAB_AUTH_COOKIE_PATH`	—	Enable cookie-jar based session auth from Netscape cookie file.
Output	`GITLAB_RESPONSE_MODE`	`json`	Response format: `json`, `compact-json`, `yaml`.
Output	`GITLAB_MAX_RESPONSE_BYTES`	`200000`	Max response payload (1KB–2MB), oversized payloads are truncated safely.
Output	`GITLAB_MAX_LOCAL_FILE_BYTES`	`250000000`	Max size for files saved locally by download tools such as job artifacts.
Output	`GITLAB_DOWNLOAD_TOKEN_SECRET`	random per process	Secret for short-lived HTTP download proxy URLs; set this for multi-replica deployments.
Output	`GITLAB_DOWNLOAD_TOKEN_TTL_SECONDS`	`300`	Lifetime of generated HTTP download proxy URLs.
Output	`GITLAB_HTTP_TIMEOUT_MS`	`20000`	Upstream GitLab HTTP timeout (1s–120s).
Output	`GITLAB_ERROR_DETAIL_MODE`	`safe/full`	Error verbosity (`safe` by default in production, `full` otherwise).
Network/TLS	`HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY`	—	Proxy settings for outbound GitLab requests, including per-host proxy bypass rules.
Network/TLS	`GITLAB_CA_CERT_PATH`	—	Custom CA certificate path (PEM).
Network/TLS	`GITLAB_CLOUDFLARE_BYPASS`	`false`	Add browser-like headers for Cloudflare-protected instances.
Network/TLS	`GITLAB_USER_AGENT`	—	Custom User-Agent for GitLab requests.

See docs/configuration.md for the complete reference.

Authentication Methods

Authentication behavior depends on mode:

REMOTE_AUTHORIZATION=true (HTTP strong mode) Each request must include Authorization: Bearer <token>, Private-Token: <token>, or Job-Token: <token>. When ENABLE_DYNAMIC_API_URL=true, each request must also include X-GitLab-API-URL.
REMOTE_AUTHORIZATION=false (default mode) The server resolves credentials in this order: GITLAB_PERSONAL_ACCESS_TOKEN -> GITLAB_JOB_TOKEN -> OAuth PKCE (GITLAB_USE_OAUTH=true) -> GITLAB_TOKEN_SCRIPT -> GITLAB_TOKEN_FILE.

Cookie-based auth (GITLAB_AUTH_COOKIE_PATH) is applied independently via a cookie jar and can work with or without a token.

See docs/authentication.md for setup guides.

Development

pnpm dev           # stdio mode with hot-reload
pnpm dev:http      # HTTP mode with hot-reload
pnpm test          # Run tests
pnpm test:watch    # Run tests in watch mode
pnpm lint          # Lint
pnpm typecheck     # Type check
pnpm inspector     # Launch MCP Inspector

Project Structure

See docs/architecture.md for detailed design documentation.

Documentation

Configuration Reference — All environment variables
Tools Reference — Complete list of MCP tools
Authentication Guide — Auth methods and setup
Deployment Guide — Docker, production, and multi-instance
Architecture — Internal design and patterns

Acknowledgements

This repository references and learns from parts of the implementation in zereight/gitlab-mcp. Thanks to the maintainers and contributors for their work.

License

MIT

This server cannot be installed

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

22hResponse time

2wRelease cycle

9Releases (12mo)

Commit activity

Issues opened vs closed

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/mcpland/gitlab-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

gitlab-mcp

Highlights

Usage

Supported clients

Authentication methods

OAuth2 setup (stdio, recommended for local interactive use)

Personal Access Token setup (stdio)

VS Code .vscode/mcp.json examples

Claude Desktop / Claude Code / Cursor

GitLab Duo (~/.gitlab/duo/mcp.json)

JetBrains AI Assistant

Remote authorization (multi-user HTTP)

Docker

Compatibility notes

MCP Server Configuration

HTTP server

Transport and entrypoint

Tool Categories

Policy & Security

Configuration

Authentication Methods

Development

Project Structure

Documentation

Acknowledgements

License

Maintenance

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API

VS Code `.vscode/mcp.json` examples

GitLab Duo (`~/.gitlab/duo/mcp.json`)