Skip to main content
Glama
@zereight/mcp-gitlab
by rokrokss

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.

Related MCP server: GitLab MR MCP

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: Settings → 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 (31 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 and job operations (19 tools)

    • milestones* — Milestone CRUD, issues, MRs, burndown (9 tools)

    • wiki* — Wiki page CRUD (5 tools)

    • releases* — Release CRUD, evidence, asset download (7 tools)

    • users* — User info, events, markdown upload, attachments (5 tools)

    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)

Tools 🛠️

  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_branch_diffs - Get the changes/diffs between two branches or commits in a GitLab project

  15. update_merge_request - Update a merge request (Either mergeRequestIid or branchName must be provided)

  16. create_note - Create a new note (comment) to an issue or merge request

  17. create_merge_request_thread - Create a new thread on a merge request

  18. mr_discussions - List discussion items for a merge request

  19. update_merge_request_note - Modify an existing merge request thread note

  20. create_merge_request_note - Add a new note to an existing merge request thread

  21. get_draft_note - Get a single draft note from a merge request

  22. list_draft_notes - List draft notes for a merge request

  23. create_draft_note - Create a draft note for a merge request

  24. update_draft_note - Update an existing draft note

  25. delete_draft_note - Delete a draft note

  26. publish_draft_note - Publish a single draft note

  27. bulk_publish_draft_notes - Publish all draft notes for a merge request

  28. update_issue_note - Modify an existing issue thread note

  29. create_issue_note - Add a new note to an existing issue thread

  30. list_issues - List issues (default: created by current user only; use scope='all' for all accessible issues)

  31. my_issues - List issues assigned to the authenticated user (defaults to open issues)

  32. get_issue - Get details of a specific issue in a GitLab project

  33. update_issue - Update an issue in a GitLab project

  34. delete_issue - Delete an issue from a GitLab project

  35. list_issue_links - List all issue links for a specific issue

  36. list_issue_discussions - List discussions for an issue in a GitLab project

  37. get_issue_link - Get a specific issue link

  38. create_issue_link - Create an issue link between two issues

  39. delete_issue_link - Delete an issue link

  40. list_namespaces - List all namespaces available to the current user

  41. get_namespace - Get details of a namespace by ID or path

  42. verify_namespace - Verify if a namespace path exists

  43. get_project - Get details of a specific project

  44. list_projects - List projects accessible by the current user

  45. list_project_members - List members of a GitLab project

  46. list_labels - List labels for a project

  47. get_label - Get a single label from a project

  48. create_label - Create a new label in a project

  49. update_label - Update an existing label in a project

  50. delete_label - Delete a label from a project

  51. list_group_projects - List projects in a GitLab group with filtering options

  52. list_wiki_pages - List wiki pages in a GitLab project

  53. get_wiki_page - Get details of a specific wiki page

  54. create_wiki_page - Create a new wiki page in a GitLab project

  55. update_wiki_page - Update an existing wiki page in a GitLab project

  56. delete_wiki_page - Delete a wiki page from a GitLab project

  57. get_repository_tree - Get the repository tree for a GitLab project (list files and directories)

  58. list_pipelines - List pipelines in a GitLab project with filtering options

  59. get_pipeline - Get details of a specific pipeline in a GitLab project

  60. list_pipeline_jobs - List all jobs in a specific pipeline

  61. list_pipeline_trigger_jobs - List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines

  62. get_pipeline_job - Get details of a GitLab pipeline job number

  63. get_pipeline_job_output - Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage

  64. create_pipeline - Create a new pipeline for a branch or tag

  65. retry_pipeline - Retry a failed or canceled pipeline

  66. cancel_pipeline - Cancel a running pipeline

  67. play_pipeline_job - Run a manual pipeline job

  68. retry_pipeline_job - Retry a failed or canceled pipeline job

  69. cancel_pipeline_job - Cancel a running pipeline job

  70. list_merge_requests - List merge requests globally or in a specific GitLab project with filtering options (project_id is now optional)

  71. list_milestones - List milestones in a GitLab project with filtering options

  72. get_milestone - Get details of a specific milestone

  73. create_milestone - Create a new milestone in a GitLab project

  74. edit_milestone - Edit an existing milestone in a GitLab project

  75. delete_milestone - Delete a milestone from a GitLab project

  76. get_milestone_issue - Get issues associated with a specific milestone

  77. get_milestone_merge_requests - Get merge requests associated with a specific milestone

  78. promote_milestone - Promote a milestone to the next stage

  79. get_milestone_burndown_events - Get burndown events for a specific milestone

  80. get_users - Get GitLab user details by usernames

  81. list_commits - List repository commits with filtering options

  82. get_commit - Get details of a specific commit

  83. get_commit_diff - Get changes/diffs of a specific commit

  84. list_group_iterations - List group iterations with filtering options

  85. upload_markdown - Upload a file to a GitLab project for use in markdown content

  86. download_attachment - Download an uploaded file from a GitLab project by secret and filename

  87. list_events - List all events for the currently authenticated user

  88. get_project_events - List all visible events for a specified project

  89. list_releases - List all releases for a project

  90. get_release - Get a release by tag name

  91. create_release - Create a new release in a GitLab project

  92. update_release - Update an existing release in a GitLab project

  93. delete_release - Delete a release from a GitLab project (does not delete the associated tag)

  94. create_release_evidence - Create release evidence for an existing release (GitLab Premium/Ultimate only)

  95. download_release_asset - Download a release asset file by direct asset path

  96. approve_merge_request - Approve a merge request (requires appropriate permissions)

  97. unapprove_merge_request - Unapprove a previously approved merge request

  98. get_merge_request_approval_state - Get merge request approval details including approvers (uses approval_state when available, otherwise falls back to approvals)

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.

Available Tools

115 tools
approve_merge_requestC

Approve a merge request. Requires appropriate permissions.

Inputs: sha, project_id, approval_password, merge_request_iid.

bulk_publish_draft_notesB

Publish all draft notes for a merge request

Inputs: project_id, merge_request_iid.

cancel_pipelineB

Cancel a running pipeline

Inputs: project_id, pipeline_id.

cancel_pipeline_jobB

Cancel a running pipeline job

Inputs: force, job_id, project_id.

create_branchB

Create a new branch in a GitLab project

Inputs: branch (required), ref, project_id.

create_draft_noteC

Create a draft note for a merge request

Inputs: body (required), position, project_id, merge_request_iid, +2 more.

create_issueB

Create a new issue in a GitLab project

Inputs: title (required), labels, issue_type, project_id, +3 more.

create_issue_noteB

Add a new note to an existing issue thread

Inputs: body (required), issue_iid, created_at, project_id, +1 more.

create_labelA

Create a new label in a project

Inputs: name (required), color (required), priority, project_id, +1 more.

create_merge_requestB

Create a new merge request in a GitLab project

Inputs: title (required), source_branch (required), target_branch (required), draft, +9 more.

create_merge_request_discussion_noteB

Add a new discussion note to an existing merge request thread

Inputs: body (required), created_at, project_id, discussion_id, +1 more.

create_merge_request_noteC

Add a new note to a merge request

Inputs: body (required), project_id, merge_request_iid.

create_merge_request_threadC

Create a new thread on a merge request

Inputs: body (required), position, created_at, project_id, +1 more.

create_milestoneB

Create a new milestone in a GitLab project

Inputs: title (required), due_date, project_id, start_date, +1 more.

create_noteC

Create a new note (comment) to an issue or merge request

Inputs: body (required), noteable_type (required), project_id, noteable_iid.

create_or_update_fileC

Create or update a single file in a GitLab project

Inputs: branch (required), content (required), file_path (required), commit_message (required), +4 more.

create_pipelineB

Create a new pipeline for a branch or tag

Inputs: ref (required), inputs, variables, project_id.

create_releaseC

Create a new release in a GitLab project

Inputs: tag_name (required), ref, name, assets, +5 more.

create_release_evidenceB

Create release evidence for an existing release (GitLab Premium/Ultimate only)

Inputs: tag_name (required), project_id.

create_repositoryB

Create a new GitLab project

Inputs: name (required), visibility, description, initialize_with_readme.

create_wiki_pageB

Create a new wiki page in a GitLab project

Inputs: title (required), content (required), format, project_id.

delete_draft_noteB

Delete a draft note

Inputs: project_id, draft_note_id, merge_request_iid.

delete_issueA

Delete an issue from a GitLab project

Inputs: issue_iid, project_id.

delete_labelB

Delete a label from a project

Inputs: label_id, project_id.

delete_merge_request_discussion_noteC

Delete a discussion note on a merge request

Inputs: note_id, project_id, discussion_id, merge_request_iid.

delete_merge_request_noteC

Delete an existing merge request note

Inputs: note_id, project_id, merge_request_iid.

delete_milestoneA

Delete a milestone from a GitLab project

Inputs: project_id, milestone_id.

delete_releaseA

Delete a release from a GitLab project (does not delete the associated tag)

Inputs: tag_name (required), project_id.

delete_wiki_pageB

Delete a wiki page from a GitLab project

Inputs: slug (required), project_id.

download_attachmentA

Download an uploaded file from a GitLab project by secret and filename. Image files (png, jpg, gif, webp, svg, bmp, ico) are returned inline as base64 image content so the AI can view them directly. Non-image files are saved to disk. Use local_path to force saving image files to disk instead.

Inputs: secret (required), filename (required), project_id (required), local_path.

download_job_artifactsA

Download the entire artifact archive (zip) for a job to a local path. Returns the saved file path.

Inputs: job_id, local_path, project_id.

download_release_assetC

Download a release asset file by direct asset path

Inputs: tag_name (required), direct_asset_path (required), project_id.

edit_milestoneC

Edit an existing milestone in a GitLab project

Inputs: title, due_date, project_id, start_date, +3 more.

fork_repositoryB

Fork a GitLab project to your account or specified namespace

Inputs: namespace, project_id.

get_branch_diffsB

Get the changes/diffs between two branches or commits in a GitLab project

Inputs: to (required), from (required), straight, project_id, +1 more.

get_commitC

Get details of a specific commit

Inputs: sha (required), stats, project_id.

get_commit_diffC

Get changes/diffs of a specific commit

Inputs: sha (required), full_diff, project_id.

get_deploymentB

Get details of a specific deployment in a GitLab project

Inputs: project_id, deployment_id.

get_draft_noteB

Get a single draft note from a merge request

Inputs: project_id, draft_note_id, merge_request_iid.

get_environmentA

Get details of a specific environment in a GitLab project

Inputs: project_id, environment_id.

get_file_contentsC

Get the contents of a file or directory from a GitLab project

Inputs: ref, path, file_path, project_id.

get_issueA

Get details of a specific issue in a GitLab project

Inputs: issue_iid, project_id.

get_job_artifact_fileA

Get the content of a single file from a job's artifacts by its path within the archive

Inputs: artifact_path (required), job_id, project_id.

get_labelC

Get a single label from a project

Inputs: label_id, project_id, include_ancestor_groups.

get_merge_requestA

Get details of a merge request with compact deployment, commit addition, and approval summaries (Either mergeRequestIid or branchName must be provided)

Inputs: project_id, source_branch, merge_request_iid.

get_merge_request_approval_stateB

Get merge request approval details including approvers (uses approval_state when available, falls back to approvals endpoint)

Inputs: project_id, merge_request_iid.

get_merge_request_conflictsA

Get the conflicts of a merge request in a GitLab project

Inputs: project_id, merge_request_iid.

get_merge_request_diffsB

Get the changes/diffs of a merge request (Either mergeRequestIid or branchName must be provided)

Inputs: view, project_id, source_branch, merge_request_iid, +1 more.

get_merge_request_noteA

Get a specific note for a merge request

Inputs: note_id, project_id, merge_request_iid.

get_merge_request_notesB

List notes for a merge request

Inputs: page, sort, order_by, per_page, +2 more.

get_merge_request_versionC

Get a specific version of a merge request

Inputs: unidiff, project_id, version_id, merge_request_iid.

get_milestoneB

Get details of a specific milestone

Inputs: project_id, milestone_id.

get_milestone_burndown_eventsC

Get burndown events for a specific milestone

Inputs: page, per_page, project_id, milestone_id.

get_milestone_issueB

Get issues associated with a specific milestone

Inputs: project_id, milestone_id.

get_milestone_merge_requestsA

Get merge requests associated with a specific milestone

Inputs: page, per_page, project_id, milestone_id.

get_namespaceB

Get details of a namespace by ID or path

Inputs: namespace_id.

get_pipelineB

Get details of a specific pipeline in a GitLab project

Inputs: project_id, pipeline_id.

get_pipeline_jobC

Get details of a GitLab pipeline job number

Inputs: limit, job_id, offset, project_id.

get_pipeline_job_outputA

Get the output/trace of a GitLab pipeline job with optional pagination to limit context window usage

Inputs: limit, job_id, offset, project_id.

get_projectC

Get details of a specific project

Inputs: project_id.

get_project_eventsB

List all visible events for a specified project. Note: before/after parameters accept date format YYYY-MM-DD only

Inputs: page, sort, after, action, +4 more.

get_releaseC

Get a release by tag name

Inputs: tag_name (required), project_id, include_html_description.

get_repository_treeC

Get the repository tree for a GitLab project (list files and directories)

Inputs: ref, path, per_page, recursive, +3 more.

get_usersA

Get GitLab user details by usernames

Inputs: usernames (required).

get_wiki_pageB

Get details of a specific wiki page

Inputs: slug (required), project_id.

list_commitsC

List repository commits with filtering options

Inputs: all, page, path, order, +9 more.

list_deploymentsC

List deployments in a GitLab project with filtering options

Inputs: ref, sha, page, sort, +7 more.

list_draft_notesC

List draft notes for a merge request

Inputs: project_id, merge_request_iid.

list_environmentsC

List environments in a GitLab project

Inputs: name, page, search, states, +2 more.

list_eventsB

List all events for the currently authenticated user. Note: before/after parameters accept date format YYYY-MM-DD only

Inputs: page, sort, after, scope, +4 more.

list_group_iterationsA

List group iterations with filtering options

Inputs: page, state, search, group_id, +6 more.

list_group_projectsC

List projects in a GitLab group with filtering options

Inputs: page, sort, search, starred, +13 more.

list_issue_discussionsB

List discussions for an issue in a GitLab project

Inputs: page, per_page, issue_iid, project_id.

list_issuesA

List issues (default: created by current user only; use scope='all' for all accessible issues)

Inputs: page, scope, state, labels, +17 more.

list_job_artifactsA

List artifact files in a job's artifacts archive. Returns file names, paths, types, and sizes.

Inputs: path, job_id, recursive, project_id.

list_labelsB

List labels for a project

Inputs: search, project_id, with_counts, include_ancestor_groups.

list_merge_request_diffsC

List merge request diffs with pagination support (Either mergeRequestIid or branchName must be provided)

Inputs: page, unidiff, per_page, project_id, +2 more.

list_merge_requestsA

List merge requests. Without project_id, lists MRs assigned to the authenticated user by default (use scope='all' for all accessible MRs). With project_id, lists MRs for that specific project.

Inputs: wip, page, sort, scope, +20 more.

list_merge_request_versionsC

List all versions of a merge request

Inputs: project_id, merge_request_iid.

list_milestonesA

List milestones in a GitLab project with filtering options

Inputs: iids, page, state, title, +6 more.

list_namespacesB

List all namespaces available to the current user

Inputs: page, owned, search, per_page.

list_pipeline_jobsC

List all jobs in a specific pipeline

Inputs: page, scope, per_page, project_id, +2 more.

list_pipelinesA

List pipelines in a GitLab project with filtering options

Inputs: ref, sha, page, sort, +9 more.

list_pipeline_trigger_jobsA

List all trigger jobs (bridges) in a specific pipeline that trigger downstream pipelines

Inputs: page, scope, per_page, project_id, +1 more.

list_project_membersB

List members of a GitLab project

Inputs: project_id (required), page, query, per_page, +3 more.

list_projectsC

List projects accessible by the current user

Inputs: page, sort, owned, search, +10 more.

list_releasesC

List all releases for a project

Inputs: page, sort, order_by, per_page, +2 more.

list_wiki_pagesC

List wiki pages in a GitLab project

Inputs: page, per_page, project_id, with_content.

merge_merge_requestC

Merge a merge request in a GitLab project

Inputs: squash, auto_merge, project_id, merge_request_iid, +4 more.

mr_discussionsC

List discussion items for a merge request

Inputs: page, per_page, project_id, merge_request_iid.

my_issuesA

List issues assigned to the authenticated user (defaults to open issues)

Inputs: page, state, labels, search, +7 more.

play_pipeline_jobC

Run a manual pipeline job

Inputs: job_id, project_id, job_variables_attributes.

promote_milestoneC

Promote a milestone to the next stage

Inputs: project_id, milestone_id.

publish_draft_noteC

Publish a single draft note

Inputs: project_id, draft_note_id, merge_request_iid.

push_filesB

Push multiple files to a GitLab project in a single commit

Inputs: files (required), branch (required), commit_message (required), project_id.

resolve_merge_request_threadC

Resolve a thread on a merge request

Inputs: resolved (required), project_id, discussion_id, merge_request_iid.

retry_pipelineA

Retry a failed or canceled pipeline

Inputs: project_id, pipeline_id.

retry_pipeline_jobB

Retry a failed or canceled pipeline job

Inputs: job_id, project_id.

search_repositoriesC

Search for GitLab projects

Inputs: search (required), page, per_page.

unapprove_merge_requestA

Unapprove a previously approved merge request. Requires appropriate permissions.

Inputs: project_id, merge_request_iid.

update_draft_noteC

Update an existing draft note

Inputs: body, position, project_id, draft_note_id, +2 more.

update_issueC

Update an issue in a GitLab project

Inputs: issue_type (required), title, labels, weight, +9 more.

update_issue_noteC

Modify an existing issue thread note

Inputs: body, note_id, resolved, issue_iid, +2 more.

update_labelB

Update an existing label in a project

Inputs: color, label_id, new_name, priority, +2 more.

update_merge_requestC

Update a merge request (Either mergeRequestIid or branchName must be provided)

Inputs: draft, title, labels, squash, +9 more.

update_merge_request_discussion_noteC

Update a discussion note on a merge request

Inputs: body, note_id, resolved, project_id, +2 more.

update_merge_request_noteC

Modify an existing merge request note

Inputs: body (required), note_id, project_id, merge_request_iid.

update_releaseC

Update an existing release in a GitLab project

Inputs: tag_name (required), name, milestones, project_id, +2 more.

update_wiki_pageA

Update an existing wiki page in a GitLab project

Inputs: slug (required), title, format, content, +1 more.

upload_markdownB

Upload a file to a GitLab project for use in markdown content

Inputs: file_path (required), project_id (required).

verify_namespaceC

Verify if a namespace path exists

Inputs: path (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.6/5.0

    Scored across 115 tools

    Disambiguation2/5

    While most tools target specific resources, several boundaries are unclear: create_note overlaps with create_issue_note and create_merge_request_note, get_merge_request_diffs overlaps with list_merge_request_diffs, and get_file_contents overlaps with get_repository_tree for directory listings. The note/discussion/thread/draft family and list_issues vs my_issues also create real misselection risk.

    Naming Consistency3/5

    The core verb_noun pattern is recognizable and mostly readable, but there are notable deviations: mr_discussions and my_issues don't follow the verb pattern, get_merge_request_notes is actually a list operation, create_or_update_file bundles two verbs, and bulk_publish_draft_notes uses an adverb prefix. These inconsistencies make the set feel mixed rather than systematic.

    Tool Count1/5

    At 115 tools this is an extreme tool count for an agent-facing server, far beyond the typical well-scoped 3-15 range. Even for GitLab's broad domain, the surface is overwhelming and selection cost is high.

    Completeness3/5

    The server covers a remarkably wide surface: MRs, issues, pipelines, releases, milestones, wiki, labels, environments, and file operations. However, several lifecycle gaps remain: no delete_file, delete_branch, delete_project, or delete_merge_request, and environments/deployments are read-only. These are notable dead ends for common workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI agents to interact with GitLab repositories, manage merge requests, review code diffs, post comments, and handle issues directly through natural language.
      125 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI agents to interact with GitLab repositories, allowing them to manage merge requests and issues including listing projects, fetching MR details and diffs, adding comments, and updating MR titles and descriptions.
      94
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to interact with GitLab repositories, monitor documentation changes, manage issues and merge requests, and search across projects with comprehensive file and commit operations.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to interact with GitLab for managing projects, branches, issues, and merge requests. It provides tools for searching code and performing file operations like reading and writing directly within repositories.
      26 npm
      MIT