Better GitLab MCP Server

An improved GitLab MCP server with bug fixes and enhancements for accessing GitLab resources.

GitHub

GitLab MCP Server

New Feature: Dynamic GitLab API URL support with connection pooling! See Dynamic API URL Documentation for details.

Star History Chart

@zereight/mcp-gitlab

GitLab MCP(Model Context Protocol) Server. Includes bug fixes and improvements over the original GitLab MCP server.

Usage

Using with Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, Amp Code

When using with the Claude App, you need to set up your API key and URLs directly.

Authentication Methods

The server supports two authentication methods:

  1. Personal Access Token (traditional method)
  2. OAuth2 (recommended for better security)

Using OAuth2 Authentication

OAuth2 provides a more secure authentication flow using browser-based authentication. When enabled, the server will:

  1. Open your browser to GitLab's authorization page
  2. Wait for you to approve the access
  3. Store the token securely for future use
  4. Automatically refresh the token when it expires

For detailed OAuth2 setup instructions, see OAuth Setup Guide.

Quick setup - first create a GitLab OAuth application:

  1. Go to your GitLab instance: Admin area → Applications
  2. Create a new application with:
    • Name: GitLab MCP Server (or any name you prefer)
    • Redirect URI: http://127.0.0.1:8888/callback
    • Scopes: Select api (provides complete read/write access to the API)
  3. Copy the Application ID (this is your Client ID)

Then configure the MCP server with OAuth:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_CLIENT_SECRET": "your_oauth_client_secret", // Required for Confidential apps only
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // use wiki api?
        "USE_MILESTONE": "false", // use milestone api?
        "USE_PIPELINE": "false" // use pipeline api?
      }
    }
  }
}

Using Personal Access Token (traditional)

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "your_gitlab_api_url",
        "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false", // use wiki api?
        "USE_MILESTONE": "false", // use milestone api?
        "USE_PIPELINE": "false" // use pipeline api?
      }
    }
  }
}

Using CLI Arguments (for clients with env var issues)

Some MCP clients (like GitHub Copilot CLI) have issues with environment variables. Use CLI arguments instead:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "-y",
        "@zereight/mcp-gitlab",
        "--token=YOUR_GITLAB_TOKEN",
        "--api-url=https://gitlab.com/api/v4"
      ],
      "tools": ["*"]
    }
  }
}

Available CLI arguments:

  • --token - GitLab Personal Access Token (replaces GITLAB_PERSONAL_ACCESS_TOKEN)
  • --api-url - GitLab API URL (replaces GITLAB_API_URL)
  • --read-only=true - Enable read-only mode (replaces GITLAB_READ_ONLY_MODE)
  • --use-wiki=true - Enable wiki API (replaces USE_GITLAB_WIKI)
  • --use-milestone=true - Enable milestone API (replaces USE_MILESTONE)
  • --use-pipeline=true - Enable pipeline API (replaces USE_PIPELINE)

CLI arguments take precedence over environment variables.

vscode .vscode/mcp.json

Using OAuth2 (Non-Confidential - Recommended):

{
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_USE_OAUTH": "true",
        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

Using OAuth2 (Confidential):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-oauth-secret",
      "description": "GitLab OAuth Client Secret",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "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:8888/callback",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false"
      }
    }
  }
}

Using Personal Access Token:

{
  "inputs": [
    {
      "type": "promptString",
      "id": "gitlab-token",
      "description": "GitLab Personal Access Token",
      "password": true
    }
  ],
  "servers": {
    "GitLab-MCP": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "${input:gitlab-token}",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "false",
        "USE_MILESTONE": "false",
        "USE_PIPELINE": "false"
      }
    }
  }
}

Strands Agents SDK (MCP Tools)

env_vars = {
        "GITLAB_PERSONAL_ACCESS_TOKEN": gitlab_access_token,
        "GITLAB_API_URL": gitlab_api_url,
        "USE_GITLAB_WIKI": use_gitlab_wiki
        # ......the rest of the optional parameters
}

stdio_gitlab_mcp_client = MCPClient(
        lambda: stdio_client(
            StdioServerParameters(
                command="npx",
                args=["-y", "@zereight/mcp-gitlab"],
                env=env_vars,
            )
        )
    )

Docker

Note: For Docker deployments, Personal Access Token is recommended. OAuth requires browser-based authentication and a local callback server, which does not work properly in containerized environments.

Using Personal Access Token (stdio) - Recommended:

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "GITLAB_PERSONAL_ACCESS_TOKEN",
        "-e",
        "GITLAB_API_URL",
        "-e",
        "GITLAB_READ_ONLY_MODE",
        "-e",
        "USE_GITLAB_WIKI",
        "-e",
        "USE_MILESTONE",
        "-e",
        "USE_PIPELINE",
        "zereight050/gitlab-mcp"
      ],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4",
        "GITLAB_READ_ONLY_MODE": "false",
        "USE_GITLAB_WIKI": "true",
        "USE_MILESTONE": "true",
        "USE_PIPELINE": "true"
      }
    }
  }
}
  • sse
docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e SSE=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "sse",
      "url": "http://localhost:3333/sse"
    }
  }
}
  • streamable-http
docker run -i --rm \
  -e HOST=0.0.0.0 \
  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e USE_GITLAB_WIKI=true \
  -e USE_MILESTONE=true \
  -e USE_PIPELINE=true \
  -e STREAMABLE_HTTP=true \
  -p 3333:3002 \
  zereight050/gitlab-mcp

{
  "mcpServers": {
    "gitlab": {
      "type": "streamable-http",
      "url": "http://localhost:3333/mcp"
    }
  }
}

Environment Variables

Authentication Configuration

  • GITLAB_PERSONAL_ACCESS_TOKEN: Your GitLab personal access token. Required in standard mode; not used when REMOTE_AUTHORIZATION=true or when using OAuth.
  • GITLAB_USE_OAUTH: Set to true to enable OAuth2 authentication instead of personal access token.
  • GITLAB_OAUTH_CLIENT_ID: The Client ID from your GitLab OAuth application. Required when using OAuth.
  • GITLAB_OAUTH_CLIENT_SECRET: The Client Secret from your GitLab OAuth application. Required only for Confidential applications.
  • GITLAB_OAUTH_REDIRECT_URI: The OAuth callback URL. Default: http://127.0.0.1:8888/callback
  • GITLAB_OAUTH_TOKEN_PATH: Custom path to store the OAuth token. Default: ~/.gitlab-mcp-token.json
  • REMOTE_AUTHORIZATION: When set to 'true', enables remote per-session authorization via HTTP headers. In this mode:
    • The server accepts GitLab PAT tokens from HTTP headers (Authorization: Bearer <token>, Private-Token: <token> or Job-Token: <token>) on a per-session basis
    • GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not required and ignored
    • Only works with Streamable HTTP transport (STREAMABLE_HTTP=true) because session management was already handled by the transport layer
    • SSE transport is disabled - attempting to use SSE with remote authorization will cause the server to exit with an error
    • Each client session can use a different token, enabling multi-user support with secure session isolation
    • Tokens are stored per session and automatically cleaned up when sessions close or timeout
  • SESSION_TIMEOUT_SECONDS: Session auth token timeout in seconds. Default: 3600 (1 hour). Valid range: 1-86400 seconds (recommended: 60+). After this period of inactivity, the auth token is removed but the transport session remains active. The client must provide auth headers again on the next request. Only applies when REMOTE_AUTHORIZATION=true.

General Configuration

  • GITLAB_API_URL: Your GitLab API URL. (Default: https://gitlab.com/api/v4)

  • GITLAB_PROJECT_ID: Default project ID. If set, Overwrite this value when making an API request.

  • GITLAB_ALLOWED_PROJECT_IDS: Optional comma-separated list of allowed project IDs. When set with a single value, acts as a default project (like the old "lock" mode). When set with multiple values, restricts access to only those projects. Examples:

    • Single value 123: MCP server can only access project 123 and uses it as default
    • Multiple values 123,456,789: MCP server can access projects 123, 456, and 789 but requires explicit project ID in requests

  • GITLAB_READ_ONLY_MODE: When set to 'true', restricts the server to only expose read-only operations. Useful for enhanced security or when write access is not needed. Also useful for using with Cursor and it's 40 tool limit.

  • GITLAB_DENIED_TOOLS_REGEX: When set as a regular expression, it excludes the matching tools.

  • USE_GITLAB_WIKI: Legacy flag. Wiki features are now enabled by default. When set to 'true', ensures wiki-related tools are included even if the wiki toolset is not explicitly listed in GITLAB_TOOLSETS.

  • USE_MILESTONE: Legacy flag. Milestone features are now enabled by default. When set to 'true', ensures milestone-related tools are included even if the milestones toolset is not explicitly listed in GITLAB_TOOLSETS.

  • USE_PIPELINE: Legacy flag. Pipeline features are now enabled by default. When set to 'true', ensures pipeline-related tools are included even if the pipelines toolset is not explicitly listed in GITLAB_TOOLSETS.

  • GITLAB_TOOLSETS: Comma-separated list of toolset IDs to enable. When empty or unset, default toolsets are used. Set to "all" to enable every toolset. Available toolsets (default toolsets marked with *):

    • merge_requests* — MR operations, notes, discussions, draft notes, threads, versions, file diffs, conflicts (34 tools)
    • issues* — Issue CRUD, notes, links, discussions (14 tools)
    • repositories* — Search, create, file contents, push, fork, tree (7 tools)
    • branches* — Branch creation, commits, diffs (4 tools)
    • projects* — Project/namespace info, group projects, iterations (8 tools)
    • labels* — Label CRUD (5 tools)
    • pipelines* — Pipeline, job, deployment, environment, and artifact operations (19 tools)
    • milestones* — Milestone CRUD, issues, MRs, burndown (9 tools)
    • wiki* — Wiki page CRUD for projects and groups (10 tools)
    • releases* — Release CRUD, evidence, asset download (7 tools)
    • users* — User info, events, markdown upload, attachments (5 tools)
    • workitems — Work item CRUD via GraphQL, type conversion, statuses, custom fields, notes, timeline events (12 tools, opt-in)
    • webhooks — Webhook listing and event inspection (3 tools, opt-in)
    • search — Code search across projects, groups, or globally (3 tools, requires advanced search or exact code search enabled)

    Note: execute_graphql is not in any toolset and must be added individually via GITLAB_TOOLS if needed. Exposing arbitrary GraphQL would allow bypassing toolset boundaries (e.g. querying data that the user intentionally disabled via toolsets like wiki or pipelines), which is a security and permission-containment concern. Keeping execute_graphql out of all toolsets and requiring explicit opt-in via GITLAB_TOOLS=execute_graphql is intentional, to align with that principle rather than for backward compatibility. CLI arg: --toolsets

  • GITLAB_TOOLS: Comma-separated list of individual tool names to add on top of the enabled toolsets (additive). Useful for cherry-picking specific tools without enabling an entire toolset. Example: GITLAB_TOOLS="list_pipelines,execute_graphql". CLI arg: --tools

    Combined logic: final tools = (tools from enabled toolsets) ∪ (GITLAB_TOOLS) ∪ (legacy flag overrides)

    Examples:

    # Default behavior (unchanged)
GITLAB_PERSONAL_ACCESS_TOKEN=xxx npx @zereight/mcp-gitlab

# Only issues and repositories
GITLAB_TOOLSETS="issues,repositories" npx @zereight/mcp-gitlab

# All toolsets
GITLAB_TOOLSETS="all" npx @zereight/mcp-gitlab

# Default toolsets + one extra pipeline tool
GITLAB_TOOLS="list_pipelines" npx @zereight/mcp-gitlab

# Specific toolsets + individual tools
GITLAB_TOOLSETS="issues,merge_requests" GITLAB_TOOLS="list_pipelines,get_pipeline" npx @zereight/mcp-gitlab

# Legacy flags still work (backward compatible)
USE_PIPELINE=true npx @zereight/mcp-gitlab

  • GITLAB_AUTH_COOKIE_PATH: Path to an authentication cookie file for GitLab instances that require cookie-based authentication. When provided, the cookie will be included in all GitLab API requests.

  • SSE: When set to 'true', enables the Server-Sent Events transport.

  • STREAMABLE_HTTP: When set to 'true', enables the Streamable HTTP transport. If both SSE and STREAMABLE_HTTP are set to 'true', the server will prioritize Streamable HTTP over SSE transport.

  • GITLAB_COMMIT_FILES_PER_PAGE: The number of files per page that GitLab returns for commit diffs. This value should match the server-side GitLab setting. Adjust this if your GitLab instance uses a custom per-page value for commit diffs.

  • GITLAB_REPO_FILE_ENCODING: Encoding for repository file create/update and related commit payloads sent to the GitLab API. Use text (default) or base64. Equivalent CLI: --repo-file-encoding=text|base64.

Performance & Security Configuration

  • HOST: Server host address. Default: 127.0.0.1 (localhost only). Set to 0.0.0.0 to allow external connections (required for Docker with port forwarding).
  • MAX_SESSIONS: Maximum number of concurrent sessions allowed. Default: 1000. Valid range: 1-10000. When limit is reached, new connections are rejected with HTTP 503.
  • MAX_REQUESTS_PER_MINUTE: Rate limit per session in requests per minute. Default: 60. Valid range: 1-1000. Exceeded requests return HTTP 429.
  • PORT: Server port. Default: 3002. Valid range: 1-65535.
  • HTTP_PROXY: HTTP proxy server URL for outgoing requests. Example: http://proxy.example.com:8080. Supports HTTP/HTTPS and SOCKS proxies (URLs starting with socks:// or socks5://). CLI arg: --http-proxy
  • HTTPS_PROXY: HTTPS proxy server URL for outgoing requests. Example: https://proxy.example.com:8080. Supports HTTP/HTTPS and SOCKS proxies. CLI arg: --https-proxy
  • NO_PROXY: Comma-separated list of hosts that should bypass the proxy. Supports:
    • Exact hostname matches (e.g., localhost, gitlab.internal.com)
    • Domain suffix matches (e.g., .internal.com matches any subdomain)
    • IP addresses (e.g., 127.0.0.1, 192.168.1.1)
    • Port-specific matches (e.g., example.com:443)
    • Wildcard * to bypass proxy for all hosts
    • Example: NO_PROXY=localhost,127.0.0.1,.internal.com
    • CLI arg: --no-proxy

Monitoring Endpoints

When using Streamable HTTP transport, the following endpoints are available:

  • /health: Health check endpoint returning server status, active sessions count, and uptime.
  • /metrics: Detailed metrics including:
    • Active and total session counts
    • Authentication metrics (failures, expirations)
    • Rate limiting statistics
    • Resource usage (memory, uptime)
    • Configuration summary

Remote Authorization Setup (Multi-User Support)

When using REMOTE_AUTHORIZATION=true, the MCP server can support multiple users, each with their own GitLab token passed via HTTP headers. This is useful for:

  • Shared MCP server instances where each user needs their own GitLab access
  • IDE integrations that can inject user-specific tokens into MCP requests

Setup Example:

# Start server with remote authorization
docker run -d \
  -e HOST=0.0.0.0 \
  -e STREAMABLE_HTTP=true \
  -e REMOTE_AUTHORIZATION=true \
  -e GITLAB_API_URL="https://gitlab.com/api/v4" \
  -e GITLAB_READ_ONLY_MODE=true \
  -e SESSION_TIMEOUT_SECONDS=3600 \
  -p 3333:3002 \
  zereight050/gitlab-mcp

Client Configuration:

Your IDE or MCP client must send one of these headers with each request:

Authorization: Bearer glpat-xxxxxxxxxxxxxxxxxxxx

or

Private-Token: glpat-xxxxxxxxxxxxxxxxxxxx

The token is stored per session (identified by mcp-session-id header) and reused for subsequent requests in the same session.

Remote Authorization Client Configuration Example with Cursor

{
  "mcpServers": {
    "GitLab": {
      "url": "http(s)://<your_mcp_gitlab_server>/mcp",
      "headers": {
        "Authorization": "Bearer glpat-..."
      }
    }
  }
}

Important Notes:

  • Remote authorization only works with Streamable HTTP transport
  • Each session is isolated - tokens from one session cannot access another session's data Tokens are automatically cleaned up when sessions close
  • Session timeout: Auth tokens expire after SESSION_TIMEOUT_SECONDS (default 1 hour) of inactivity. After timeout, the client must send auth headers again. The transport session remains active.
  • Each request resets the timeout timer for that session
  • Rate limiting: Each session is limited to MAX_REQUESTS_PER_MINUTE requests per minute (default 60)
  • Capacity limit: Server accepts up to MAX_SESSIONS concurrent sessions (default 1000)

MCP OAuth Setup (Claude.ai Native OAuth)

When using GITLAB_MCP_OAUTH=true, the server acts as an OAuth proxy to your GitLab instance. Claude.ai (and any MCP-spec-compliant client) handles the entire browser authentication flow automatically — no manual Personal Access Token management needed.

Prerequisites:

A pre-registered GitLab OAuth application is required. GitLab restricts dynamically registered (unverified) applications to the mcp scope, which is insufficient for API calls (need api or read_api).

  1. Go to your GitLab instance → Admin Area > Applications (instance-wide) or User Settings > Applications (personal)
  2. Create a new application with:
    • Confidential: unchecked
    • Scopes: api, read_api, read_user
  3. Save and copy the Application ID — this is your GITLAB_OAUTH_APP_ID

How it works:

  1. User adds your MCP server URL in Claude.ai
  2. Claude.ai discovers OAuth endpoints via /.well-known/oauth-authorization-server
  3. Claude.ai registers itself via Dynamic Client Registration (POST /register) — handled locally by the MCP server (each client gets a virtual client ID)
  4. Claude.ai redirects the user's browser to GitLab's login page using the pre-registered OAuth application
  5. User authenticates; GitLab redirects back to https://claude.ai/api/mcp/auth_callback
  6. Claude.ai sends Authorization: Bearer <token> on every MCP request
  7. Server validates the token with GitLab and stores it per session

Server setup:

docker run -d \
  -e STREAMABLE_HTTP=true \
  -e GITLAB_MCP_OAUTH=true \
  -e GITLAB_OAUTH_APP_ID="your-gitlab-oauth-app-client-id" \
  -e GITLAB_API_URL="https://gitlab.example.com/api/v4" \
  -e MCP_SERVER_URL="https://your-mcp-server.example.com" \
  -p 3002:3002 \
  zereight050/gitlab-mcp

For local development (HTTP allowed):

MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL=true \
STREAMABLE_HTTP=true \
GITLAB_MCP_OAUTH=true \
GITLAB_OAUTH_APP_ID=your-gitlab-oauth-app-client-id \
MCP_SERVER_URL=http://localhost:3002 \
GITLAB_API_URL=https://gitlab.com/api/v4 \
node build/index.js

Claude.ai configuration:

{
  "mcpServers": {
    "GitLab": {
      "url": "https://your-mcp-server.example.com/mcp"
    }
  }
}

No headers field is needed — Claude.ai obtains the token via OAuth automatically.

Environment variables:

VariableRequiredDescription
GITLAB_MCP_OAUTHYesSet to true to enable
GITLAB_OAUTH_APP_IDYesClient ID of the pre-registered GitLab OAuth application
MCP_SERVER_URLYesPublic HTTPS URL of your MCP server
GITLAB_API_URLYesYour GitLab instance API URL (e.g. https://gitlab.com/api/v4)
STREAMABLE_HTTPYesMust be true (SSE is not supported)
MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URLNoSet true for local HTTP dev only

Important Notes:

  • MCP OAuth only works with Streamable HTTP transport (SSE=true is incompatible)
  • Each user session stores its own OAuth token — sessions are fully isolated
  • Session timeout, rate limiting, and capacity limits apply identically to the REMOTE_AUTHORIZATION mode (SESSION_TIMEOUT_SECONDS, MAX_REQUESTS_PER_MINUTE, MAX_SESSIONS)

Tools 🛠️

Click to expand
  1. merge_merge_request - Merge a merge request in a GitLab project
  2. create_or_update_file - Create or update a single file in a GitLab project
  3. search_repositories - Search for GitLab projects
  4. create_repository - Create a new GitLab project
  5. get_file_contents - Get the contents of a file or directory from a GitLab project
  6. push_files - Push multiple files to a GitLab project in a single commit
  7. create_issue - Create a new issue in a GitLab project
  8. create_merge_request - Create a new merge request in a GitLab project
  9. fork_repository - Fork a GitLab project to your account or specified namespace
  10. create_branch - Create a new branch in a GitLab project
  11. get_merge_request - Get details of a merge request with compact deployment summary, behind-count, commit addition summary, and approval summary (Either mergeRequestIid or branchName must be provided)
  12. get_merge_request_diffs - Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)
  13. list_merge_request_diffs - List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)
  14. get_merge_request_conflicts - Get the conflicts of a merge request in a GitLab project
  15. list_merge_request_changed_files - STEP 1 of code review workflow. Returns ONLY the list of changed file paths in a merge request — WITHOUT diff content. Call this first to get file paths, then call get_merge_request_file_diff with multiple files in a single batched call (recommended 3-5 files per call). Supports excluded_file_patterns filtering using regex. (Either mergeRequestIid or branchName must be provided)
  16. get_merge_request_file_diff - STEP 2 of code review workflow. Get diffs for one or more files from a merge request. Call list_merge_request_changed_files first, then pass them as an array to fetch diffs efficiently. Batching multiple files (recommended 3-5) is supported. (Either mergeRequestIid or branchName must be provided)
  17. list_merge_request_versions - List all versions of a merge request
  18. get_merge_request_version - Get a specific version of a merge request
  19. get_branch_diffs - Get the changes/diffs between two branches or commits in a GitLab project
  20. update_merge_request - Update a merge request (Either mergeRequestIid or branchName must be provided)
  21. create_note - Create a new note (comment) to an issue or merge request
  22. create_merge_request_thread - Create a new thread on a merge request
  23. mr_discussions - List discussion items for a merge request
  24. resolve_merge_request_thread - Resolve a thread on a merge request
  25. update_merge_request_note - Modify an existing merge request thread note
  26. create_merge_request_note - Add a new note to an existing merge request thread
  27. delete_merge_request_discussion_note - Delete a discussion note on a merge request
  28. update_merge_request_discussion_note - Update a discussion note on a merge request
  29. create_merge_request_discussion_note - Add a new discussion note to an existing merge request thread
  30. delete_merge_request_note - Delete an existing merge request note
  31. get_merge_request_note - Get a specific note for a merge request
  32. get_merge_request_notes - List notes for a merge request
  33. get_draft_note - Get a single draft note from a merge request
  34. list_draft_notes - List draft notes for a merge request
  35. create_draft_note - Create a draft note for a merge request
  36. update_draft_note - Update an existing draft note
  37. delete_draft_note - Delete a draft note
  38. publish_draft_note - Publish a single draft note
  39. bulk_publish_draft_notes - Publish all draft notes for a merge request
  40. list_merge_requests - List merge requests globally or in a specific GitLab project with filtering options (project_id is now optional)
  41. approve_merge_request - Approve a merge request (requires appropriate permissions)
  42. unapprove_merge_request - Unapprove a previously approved merge request
  43. get_merge_request_approval_state - Get merge request approval details including approvers (uses approval_state when available, otherwise falls back to approvals)
  44. update_issue_note - Modify an existing issue thread note
  45. create_issue_note - Add a new note to an existing issue thread
  46. list_issues - List issues (default: created by current user only; use scope='all' for all accessible issues)
  47. my_issues - List issues assigned to the authenticated user (defaults to open issues)
  48. get_issue - Get details of a specific issue in a GitLab project
  49. update_issue - Update an issue in a GitLab project
  50. delete_issue - Delete an issue from a GitLab project
  51. list_issue_links - List all issue links for a specific issue
  52. list_issue_discussions - List discussions for an issue in a GitLab project
  53. get_issue_link - Get a specific issue link
  54. create_issue_link - Create an issue link between two issues
  55. delete_issue_link - Delete an issue link
  56. list_namespaces - List all namespaces available to the current user
  57. get_namespace - Get details of a namespace by ID or path
  58. verify_namespace - Verify if a namespace path exists
  59. get_project - Get details of a specific project
  60. list_projects - List projects accessible by the current user
  61. list_project_members - List members of a GitLab project
  62. list_group_projects - List projects in a GitLab group with filtering options
  63. list_group_iterations - List group iterations with filtering options
  64. list_labels - List labels for a project
  65. get_label - Get a single label from a project
  66. create_label - Create a new label in a project
  67. update_label - Update an existing label in a project
  68. delete_label - Delete a label from a project
  69. list_pipelines - List pipelines in a GitLab project with filtering options
  70. get_pipeline - Get details of a specific pipeline in a GitLab project
  71. list_pipeline_jobs - List all jobs in a specific pipeline
  72. list_pipeline_trigger_jobs - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines
  73. get_pipeline_job - Get details of a GitLab pipeline job number
  74. get_pipeline_job_output - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage
  75. create_pipeline - Create a new pipeline for a branch or tag
  76. retry_pipeline - Retry a failed or canceled pipeline
  77. cancel_pipeline - Cancel a running pipeline
  78. play_pipeline_job - Run a manual pipeline job
  79. retry_pipeline_job - Retry a failed or canceled pipeline job
  80. cancel_pipeline_job - Cancel a running pipeline job
  81. list_deployments - List deployments in a GitLab project with filtering options
  82. get_deployment - Get details of a specific deployment in a GitLab project
  83. list_environments - List environments in a GitLab project
  84. get_environment - Get details of a specific environment in a GitLab project
  85. list_job_artifacts - List artifact files in a job's artifacts archive. Returns file names, paths, types, and sizes
  86. download_job_artifacts - Download the entire artifact archive (zip) for a job to a local path. Returns the saved file path
  87. get_job_artifact_file - Get the content of a single file from a job's artifacts by its path within the archive
  88. list_milestones - List milestones in a GitLab project with filtering options
  89. get_milestone - Get details of a specific milestone
  90. create_milestone - Create a new milestone in a GitLab project
  91. edit_milestone - Edit an existing milestone in a GitLab project
  92. delete_milestone - Delete a milestone from a GitLab project
  93. get_milestone_issue - Get issues associated with a specific milestone
  94. get_milestone_merge_requests - Get merge requests associated with a specific milestone
  95. promote_milestone - Promote a milestone to the next stage
  96. get_milestone_burndown_events - Get burndown events for a specific milestone
  97. list_wiki_pages - List wiki pages in a GitLab project
  98. get_wiki_page - Get details of a specific wiki page
  99. create_wiki_page - Create a new wiki page in a GitLab project
  100. update_wiki_page - Update an existing wiki page in a GitLab project
  101. delete_wiki_page - Delete a wiki page from a GitLab project
  102. list_group_wiki_pages - List wiki pages in a GitLab group
  103. get_group_wiki_page - Get details of a specific group wiki page
  104. create_group_wiki_page - Create a new wiki page in a GitLab group
  105. update_group_wiki_page - Update an existing wiki page in a GitLab group
  106. delete_group_wiki_page - Delete a wiki page from a GitLab group
  107. get_repository_tree - Get the repository tree for a GitLab project (list files and directories)
  108. list_commits - List repository commits with filtering options
  109. get_commit - Get details of a specific commit
  110. get_commit_diff - Get changes/diffs of a specific commit
  111. list_releases - List all releases for a project
  112. get_release - Get a release by tag name
  113. create_release - Create a new release in a GitLab project
  114. update_release - Update an existing release in a GitLab project
  115. delete_release - Delete a release from a GitLab project (does not delete the associated tag)
  116. create_release_evidence - Create release evidence for an existing release (GitLab Premium/Ultimate only)
  117. download_release_asset - Download a release asset file by direct asset path
  118. get_users - Get GitLab user details by usernames
  119. list_events - List all events for the currently authenticated user
  120. get_project_events - List all visible events for a specified project
  121. upload_markdown - Upload a file to a GitLab project for use in markdown content
  122. download_attachment - Download an uploaded file from a GitLab project by secret and filename
  123. get_work_item - Get a single work item with full details including status, hierarchy (parent/children), type, labels, assignees, and all widgets
  124. list_work_items - List work items in a project with filters (type, state, search, assignees, labels). Returns items with status and hierarchy info
  125. create_work_item - Create a new work item (issue, task, incident, test_case, epic, key_result, objective, requirement, ticket). Supports setting title, description, labels, assignees, weight, parent, health status, start/due dates, milestone, and confidentiality
  126. update_work_item - Update a work item. Can modify title, description, labels, assignees, weight, state, status, parent hierarchy, children, health status, start/due dates, milestone, confidentiality, linked items, and custom fields
  127. convert_work_item_type - Convert a work item to a different type (e.g. issue to task, task to incident)
  128. list_work_item_statuses - List available statuses for a work item type in a project. Requires GitLab Premium/Ultimate with configurable statuses
  129. list_custom_field_definitions - List available custom field definitions for a work item type in a project. Returns field names, types, and IDs needed for setting custom fields via update_work_item
  130. move_work_item - Move a work item (issue, task, etc.) to a different project. Uses GitLab GraphQL issueMove mutation
  131. list_work_item_notes - List notes and discussions on a work item. Returns threaded discussions with author, body, timestamps, and system/internal flags
  132. create_work_item_note - Add a note/comment to a work item. Supports Markdown, internal notes, and threaded replies
  133. get_timeline_events - List timeline events for an incident. Returns chronological events with notes, timestamps, and tags
  134. create_timeline_event - Create a timeline event on an incident. Supports tags: 'Start time', 'End time', 'Impact detected', 'Response initiated', 'Impact mitigated', 'Cause identified'
  135. list_webhooks - List all configured webhooks for a GitLab project or group. Provide either project_id or group_id
  136. list_webhook_events - List recent webhook events (past 7 days) for a project or group webhook. Use summary mode for overview, then get_webhook_event for full details
  137. get_webhook_event - Get full details of a specific webhook event by ID, including request/response payloads
  138. search_code - Search for code across all projects on the GitLab instance (requires advanced search or exact code search to be enabled)
  139. search_project_code - Search for code within a specific GitLab project (requires advanced search or exact code search to be enabled)
  140. search_group_code - Search for code within a specific GitLab group (requires advanced search or exact code search to be enabled)
  141. execute_graphql - Execute a GitLab GraphQL query

Testing 🧪

The project includes comprehensive test coverage including remote authorization:

# Run all tests (API validation + remote auth)
npm test

# Run only remote authorization tests
npm run test:remote-auth

# Run all tests including readonly MCP tests
npm run test:all

# Run only API validation
npm run test:integration

All remote authorization tests use a mock GitLab server and do not require actual GitLab credentials.

Related Servers