GitLab MCP Server

A production-grade Model Context Protocol (MCP) server for GitLab. Engineered for autonomous AI coding assistants, agents, and pair programmers — featuring deep integration with Google Antigravity, Claude Code, Cursor, and VS Code.

Overview

This repository provides a comprehensive, production-ready GitLab Model Context Protocol (MCP) server. It exposes a rich set of 218 tools across 20 toolsets, granting AI agents full read, write, and orchestration capabilities across GitLab SaaS (gitlab.com) or self-hosted GitLab CE/EE instances.

Key Features & Capabilities

• 🚀 CI/CD Runner Management: Built-in 6-tool suite for managing GitLab runners (list, inspect, pause, resume, delete, and job execution logs).

• 🤖 Native Google Antigravity Integration: Pre-configured and tested for both Antigravity IDE and Antigravity CLI via Docker.

• 🛡️ Fine-Grained Safety Tiers: Three distinct permission modes (full, modify, readonly) preventing accidental deletions in production environments.

• ⚡ Dynamic On-Demand Toolsets: Keep agent context windows lean by starting with 9 default toolsets and loading opt-in toolsets at runtime using discover_tools.

• 🔌 Multi-Transport Architecture: Native support for stdio (local process IPC), Streamable HTTP (remote sessions), and SSE (Server-Sent Events).

Related MCP server: GitLab MCP Server

Table of Contents

• Toolsets Overview

• Spotlight: CI/CD Runner Management

• Quick Start & Client Configurations

  • Google Antigravity IDE & CLI

  • Docker Setup (Recommended)

  • Claude Code & Claude Desktop

  • Cursor IDE

  • VS Code / GitHub Copilot

• Authentication Methods

• Security & Permission Modes

• Environment Variables Reference

• Tools by Category

• Complete Tool Inventory (218 Tools)

• How Custom Tools Are Built

• Development & Verification

Toolsets Overview

Tools are grouped into 20 domain toolsets. The server boots with 9 core toolsets active by default (114 tools) to minimize token overhead. Opt-in toolsets (104 tools) can be activated via environment variables or on the fly by the AI.

(Plus 2 standalone meta tools: discover_tools and execute_graphql.)

Spotlight: CI/CD Runner Management

Standard GitLab MCP servers only support pipelines and jobs, leaving the underlying runner infrastructure inaccessible. I designed and implemented the runners toolset to bridge this gap.

The 6 Custom Runner Tools

1. list_runners

   • List GitLab CI/CD runners across instance, group, or project levels.

   • Filters:

     • type: instance_type (shared runners), group_type, or project_type

     • status: online, offline, stale, never_contacted, active, paused

     • tag_list: Filter by tags (e.g. ["docker", "gpu", "linux"])

     • project_id / group_id: Scope results to a specific project or group

2. get_runner

   • Retrieve deep runner specifications:

     • Platform, architecture, software version, IP address, tag list, active status, maximum timeout, and timestamp of last contact.

3. pause_runner

   • Temporarily disable a runner from picking up new CI/CD jobs. The runner remains registered but inactive, perfect for maintenance or host patching.

4. resume_runner

   • Re-enable a paused runner so it immediately resumes job consumption from the queue.

5. delete_runner (destructive)

   • Permanently remove a decommissioned runner from the GitLab instance.

6. list_runner_jobs

   • Audit all jobs executed by a specific runner.

   • Filter by status (running, success, failed, canceled) to quickly diagnose runner-specific failures.

Practical Scenarios

# Scenario 1: Triage offline or stale runners
list_runners(status: "stale")                # Find runners that missed heartbeat
get_runner(runner_id: "53980205")            # Inspect IP, OS, and tags
list_runner_jobs(runner_id: "53980205", status: "failed") # Check failed builds

# Scenario 2: Host maintenance workflow
pause_runner(runner_id: "53980205")          # Safely drain runner
# ... apply updates or reboot host machine ...
resume_runner(runner_id: "53980205")         # Put runner back in rotation

Quick Start & Client Configurations

Google Antigravity IDE & CLI

My primary environment is Google Antigravity. To configure this MCP in Antigravity:

Edit your MCP configuration file:

• Antigravity IDE: ~/.gemini/antigravity/mcp_config.json

• Antigravity CLI: ~/.gemini/antigravity-cli/mcp_config.json

{
  "mcpServers": {
    "gitlab-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GITLAB_PERSONAL_ACCESS_TOKEN=your_personal_access_token",
        "-e", "GITLAB_API_URL=https://gitlab.com/api/v4",
        "-e", "GITLAB_TOOLSETS=all",
        "custom-gitlab-mcp:latest"
      ]
    }
  }
}

Docker Setup (Recommended)

Running inside Docker ensures all Node.js and TypeScript dependencies are isolated.

# 1. Clone this repository
git clone https://github.com/aryannverse/Custom-GitLab-MCP.git
cd Custom-GitLab-MCP

# 2. Build the Docker image
docker build -t custom-gitlab-mcp:latest .

# 3. Test running the image
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"whoami","arguments":{}}}' | \
  docker run -i --rm \
    -e GITLAB_PERSONAL_ACCESS_TOKEN="your_gitlab_token" \
    -e GITLAB_API_URL="https://gitlab.com/api/v4" \
    -e GITLAB_TOOLSETS="all" \
    custom-gitlab-mcp:latest

Claude Code & Claude Desktop

In claude_desktop_config.json:

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GITLAB_PERSONAL_ACCESS_TOKEN=your_token_here",
        "-e", "GITLAB_API_URL=https://gitlab.com/api/v4",
        "-e", "GITLAB_TOOLSETS=all",
        "custom-gitlab-mcp:latest"
      ]
    }
  }
}

Cursor IDE

In Cursor Settings > Features > MCP:

• Name: GitLab

• Type: command

• Command:

  docker run -i --rm -e GITLAB_PERSONAL_ACCESS_TOKEN=your_token -e GITLAB_API_URL=https://gitlab.com/api/v4 -e GITLAB_TOOLSETS=all custom-gitlab-mcp:latest

VS Code / GitHub Copilot

In .vscode/mcp.json:

{
  "servers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "GITLAB_PERSONAL_ACCESS_TOKEN=your_token",
        "-e", "GITLAB_API_URL=https://gitlab.com/api/v4",
        "-e", "GITLAB_TOOLSETS=all",
        "custom-gitlab-mcp:latest"
      ]
    }
  }
}

Authentication Methods

The server supports 4 authentication mechanisms:

1. Personal Access Token (PAT) (Recommended)

   • Simplest configuration. Create a PAT in GitLab under User Settings > Access Tokens with scope api (or read_api for read-only setups).

   • Set via GITLAB_PERSONAL_ACCESS_TOKEN=glpat-...

2. Local OAuth 2.0 PKCE Browser Flow

   • Recommended when you do not wish to store long-lived tokens on disk.

   • Set GITLAB_USE_OAUTH=true, GITLAB_OAUTH_CLIENT_ID, and GITLAB_OAUTH_REDIRECT_URI.

   • On first request, automatically launches your default browser for user authentication.

3. Remote MCP OAuth Proxy

   • For remote web clients like Claude.ai. Unauthenticated calls receive 401 + WWW-Authenticate, initiating standard OAuth 2.0 discovery.

   • Set GITLAB_MCP_OAUTH=true and STREAMABLE_HTTP=true.

4. Remote Multi-User Authorization

   • For shared multi-user server instances.

   • Set REMOTE_AUTHORIZATION=true and STREAMABLE_HTTP=true. Callers pass their token per HTTP session via Authorization: Bearer <token> or Private-Token: <token>.

Security & Permission Modes

To safeguard repositories against accidental destruction by autonomous agents, configure the permission mode:

# Full access — allows all operations (default)
GITLAB_PERMISSION_MODE=full

# Modify mode — allows reads, creates, and updates, but strictly blocks all 28 permanent delete tools
GITLAB_PERMISSION_MODE=modify

# Read-only mode — allows only the 117 query tools, rejecting all modifications
GITLAB_PERMISSION_MODE=readonly

Tool Filtering Controls

• GITLAB_TOOLSETS: Comma-separated list of toolsets to enable (e.g. runners,pipelines,merge_requests) or all.

• GITLAB_TOOLS: Comma-separated list of individual tools to allow (e.g. list_runners,get_runner).

• GITLAB_DENIED_TOOLS_REGEX: Regular expression pattern to deny specific tools (e.g. ^delete_.*).

Environment Variables Reference

Tools by Category

merge_requests (43 tools) — Default: Active

• merge_merge_request (destructive) — Merge a merge request

• approve_merge_request — Approve a merge request

• unapprove_merge_request — Unapprove a merge request

• get_merge_request_approval_state (read-only) — Get merge request approval details including approvers

• get_branch (read-only) — Get branch details (commit, protection status)

• list_branches (read-only) — List branches in project with search filter

• get_merge_request_conflicts (read-only) — Get the conflicts of a merge request

• list_merge_request_pipelines (read-only) — List pipelines for a merge request with pagination

• get_merge_request (read-only) — Get details of a merge request (mergeRequestIid or branchName required). Set include_summaries=true for deployment/commit/approval summaries

• get_merge_request_diffs (read-only) — Get the changes/diffs of a merge request (mergeRequestIid or branchName required)

• list_merge_request_changed_files (read-only) — List changed file paths in a merge request without diff content (mergeRequestIid or branchName required)

• list_merge_request_diffs (read-only) — List merge request diffs with pagination (mergeRequestIid or branchName required)

• get_merge_request_file_diff (read-only) — Get diffs for specific files from a merge request (mergeRequestIid or branchName required)

• list_merge_request_versions (read-only) — List all versions of a merge request

• get_merge_request_version (read-only) — Get a specific version of a merge request

• update_merge_request — Update a merge request (mergeRequestIid or branchName required)

• create_merge_request — Create a new merge request

• list_merge_requests (read-only) — List merge requests (without project_id: user's MRs; with project_id: project MRs)

• get_branch_diffs (read-only) — Get diffs between two branches or commits

• mr_discussions (read-only) — List discussion items for a merge request

• create_merge_request_note — Add a new note to a merge request

• update_merge_request_note — Modify an existing merge request note

• delete_merge_request_note (destructive) — Delete an existing merge request note

• get_merge_request_note (read-only) — Get a specific note for a merge request

• get_merge_request_notes (read-only) — List notes for a merge request

• delete_merge_request_discussion_note (destructive) — Delete a discussion note on a merge request

• update_merge_request_discussion_note — Update a discussion note on a merge request

• create_merge_request_discussion_note — Add a new discussion note to an existing merge request thread

• get_draft_note (read-only) — Get a single draft note from a merge request

• list_draft_notes (read-only) — List draft notes for a merge request

• create_draft_note — Create a draft note for a merge request

• update_draft_note — Update an existing draft note

• delete_draft_note (destructive) — Delete a draft note

• publish_draft_note — Publish a single draft note

• bulk_publish_draft_notes — Publish all draft notes for a merge request

• create_merge_request_thread — Create a new thread on a merge request

• resolve_merge_request_thread — Resolve a thread on a merge request

• list_merge_request_emoji_reactions (read-only) — List all emoji reactions on a merge request

• list_merge_request_note_emoji_reactions (read-only) — List all emoji reactions on a merge request note. Pass discussion_id for discussion thread replies.

• create_merge_request_emoji_reaction — Add an emoji reaction to a merge request (e.g. thumbsup, rocket, eyes)

• delete_merge_request_emoji_reaction (destructive) — Remove an emoji reaction from a merge request

• create_merge_request_note_emoji_reaction — Add an emoji reaction to a merge request note. Pass discussion_id for discussion thread replies.

• delete_merge_request_note_emoji_reaction (destructive) — Remove an emoji reaction from a merge request note. Pass discussion_id for discussion thread replies.

issues (24 tools) — Default: Active

• create_issue — Create a new issue

• list_issues (read-only) — List issues (default: created by current user; use scope='all' for all)

• my_issues (read-only) — List issues assigned to the authenticated user

• get_issue (read-only) — Get details of a specific issue. Returns a slim milestone by default; set full_response=true for the complete milestone object

• update_issue — Update an issue. Returns a slim confirmation by default; set full_response=true for the complete updated issue object

• update_issue_description_patch — Apply a patch (search/replace or unified diff) to an issue description. Reduces token usage by allowing small changes without sending the full description. Supports dry_run to preview changes and create_note to summarize updates.

• delete_issue (destructive) — Delete an issue

• list_todos (read-only) — List GitLab to-do items for the current user

• mark_todo_done — Mark a GitLab to-do item as done

• mark_all_todos_done — Mark all pending GitLab to-do items as done for the current user

• create_issue_note — Add a note to an issue, optionally replying to a discussion thread

• update_issue_note — Modify an existing issue thread note

• list_issue_links (read-only) — List all issue links for a specific issue

• list_issue_discussions (read-only) — List discussions for an issue

• get_issue_link (read-only) — Get a specific issue link

• create_issue_link — Create an issue link between two issues

• delete_issue_link (destructive) — Delete an issue link

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

• list_issue_emoji_reactions (read-only) — List all emoji reactions on an issue

• list_issue_note_emoji_reactions (read-only) — List all emoji reactions on an issue note. Pass discussion_id for discussion thread replies.

• create_issue_emoji_reaction — Add an emoji reaction to an issue (e.g. thumbsup, rocket, eyes)

• delete_issue_emoji_reaction (destructive) — Remove an emoji reaction from an issue

• create_issue_note_emoji_reaction — Add an emoji reaction to an issue note. Pass discussion_id for discussion thread replies.

• delete_issue_note_emoji_reaction (destructive) — Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.

repositories (7 tools) — Default: Active

• search_repositories (read-only) — Search for GitLab projects

• create_repository — Create a new GitLab project

• get_file_contents (read-only) — Get contents of a file or directory from a GitLab project

• push_files (destructive) — Push multiple files in a single commit

• create_or_update_file — Create or update a file in a GitLab project

• fork_repository — Fork a project to your account or specified namespace

• get_repository_tree (read-only) — List files and directories in a repository

branches (15 tools) — Default: Active

• create_branch — Create a new branch

• get_branch (read-only) — Get branch details (commit, protection status)

• list_branches (read-only) — List branches in project with search filter

• delete_branch (destructive) — Delete branch from project

• list_protected_branches (read-only) — List protected branches in a project, supports search filter

• get_protected_branch (read-only) — Get details of a single protected branch (access levels, force push settings)

• protect_branch (destructive) — Protect a repository branch (set push/merge/unprotect access levels)

• unprotect_branch (destructive) — Remove protection from a previously protected branch

• update_default_branch (destructive) — Change the default branch of a project

• list_commits (read-only) — List repository commits with filtering options

• get_commit (read-only) — Get details of a specific commit

• get_commit_diff (read-only) — Get changes/diffs of a specific commit

• get_file_blame (read-only) — Get git blame for a file at a given ref. Each entry maps a contiguous range of source lines to the commit that last changed them (id, author, authored_date, message). Use range_start/range_end to limit blame to specific lines.

• list_commit_statuses (read-only) — List statuses for a commit

• create_commit_status — Create or update the status of a commit

projects (10 tools) — Default: Active

• get_project (read-only) — Get details of a specific project

• list_projects (read-only) — List projects accessible by the current user

• update_project — Update project settings such as description, visibility, default branch, and feature access levels

• list_project_members (read-only) — List members of a GitLab project

• list_namespaces (read-only) — List all namespaces (users and groups) available to the current user. Filter by kind='group' for groups only.

• get_namespace (read-only) — Get details of a namespace (user or group) by ID or path. Groups are namespaces with kind='group'.

• verify_namespace (read-only) — Verify if a namespace path exists. Use parent_id to scope the check to a specific parent namespace — required for nested namespaces where the same path may exist under different parents.

• list_group_projects (read-only) — List projects in a group

• list_group_iterations (read-only) — List group iterations with filtering options

• health_check (read-only) — Verify server status and authentication

labels (5 tools) — Default: Active

• list_labels (read-only) — List labels for a project

• get_label (read-only) — Get a single label from a project

• create_label — Create a new label in a project

• update_label — Update an existing label in a project

• delete_label (destructive) — Delete a label from a project

ci (4 tools) — Default: Active

• validate_ci_lint (read-only) — Validate provided GitLab CI/CD YAML content for a project

• validate_project_ci_lint (read-only) — Validate an existing .gitlab-ci.yml configuration for a project

• list_ci_catalog_resources (read-only) — List GitLab CI/CD Catalog resources/components visible to the user

• get_ci_catalog_resource (read-only) — Get details for a GitLab CI/CD Catalog resource, including versions and components

groups (1 tools) — Default: Active

• create_group — Create new group or subgroup

pipelines (19 tools) — Opt-in (GITLAB_TOOLSETS=pipelines)

• list_pipelines (read-only) — List pipelines with filtering options

• get_pipeline (read-only) — Get details of a specific pipeline

• list_deployments (read-only) — List deployments with filtering options

• get_deployment (read-only) — Get details of a specific deployment

• list_environments (read-only) — List environments in a project

• get_environment (read-only) — Get details of a specific environment

• list_pipeline_jobs (read-only) — List all jobs in a specific pipeline

• list_pipeline_trigger_jobs (read-only) — List trigger jobs (bridges) in a pipeline

• get_pipeline_job (read-only) — Get details of a GitLab pipeline job number

• get_pipeline_job_output (read-only) — Get the output/trace of a pipeline job with optional pagination

• create_pipeline — Create a new pipeline for a branch or tag

• retry_pipeline — Retry a failed or canceled pipeline

• cancel_pipeline — Cancel a running pipeline

• play_pipeline_job — Run a manual pipeline job

• retry_pipeline_job — Retry a failed or canceled pipeline job

• cancel_pipeline_job — Cancel a running pipeline job

• list_job_artifacts (read-only) — List artifact files in a job's archive

• download_job_artifacts (read-only) — Download job artifact archive (zip) and save to a local path

• get_job_artifact_file (read-only) — Get content of a single file from a job's artifacts

milestones (17 tools) — Opt-in (GITLAB_TOOLSETS=milestones)

• list_milestones (read-only) — List milestones with filtering options

• get_milestone (read-only) — Get details of a specific milestone

• create_milestone — Create a new milestone

• edit_milestone — Edit an existing milestone

• delete_milestone (destructive) — Delete a milestone

• get_milestone_issue (read-only) — Get issues associated with a specific milestone

• get_milestone_merge_requests (read-only) — Get merge requests associated with a specific milestone

• promote_milestone — Promote a milestone to the next stage

• get_milestone_burndown_events (read-only) — Get burndown events for a specific milestone

• list_group_milestones (read-only) — List group milestones with filtering options

• get_group_milestone (read-only) — Get details of a specific group milestone

• create_group_milestone — Create a new group milestone

• edit_group_milestone — Edit an existing group milestone

• delete_group_milestone (destructive) — Delete a group milestone

• get_group_milestone_issue (read-only) — Get issues associated with a specific group milestone

• get_group_milestone_merge_requests (read-only) — Get merge requests associated with a specific group milestone

• get_group_milestone_burndown_events (read-only) — Get burndown events for a specific group milestone

wiki (10 tools) — Opt-in (GITLAB_TOOLSETS=wiki)

• list_wiki_pages (read-only) — List wiki pages in a project

• get_wiki_page (read-only) — Get details of a specific wiki page

• create_wiki_page — Create a wiki page in a project

• update_wiki_page — Update a wiki page in a project

• delete_wiki_page (destructive) — Delete a wiki page from a project

• list_group_wiki_pages (read-only) — List wiki pages in a group

• get_group_wiki_page (read-only) — Get details of a specific group wiki page

• create_group_wiki_page — Create a wiki page in a group

• update_group_wiki_page — Update a wiki page in a group

• delete_group_wiki_page (destructive) — Delete a wiki page from a group

releases (7 tools) — Opt-in (GITLAB_TOOLSETS=releases)

• list_releases (read-only) — List all releases for a project

• get_release (read-only) — Get a release by tag name

• create_release — Create a new release

• update_release — Update an existing release

• delete_release (destructive) — Delete a release (does not delete the tag)

• create_release_evidence — Create release evidence (Premium/Ultimate)

• download_release_asset (read-only) — Download a release asset file by direct asset path

tags (5 tools) — Opt-in (GITLAB_TOOLSETS=tags)

• list_tags (read-only) — List repository tags for a project

• get_tag (read-only) — Get a repository tag by name

• create_tag — Create a new repository tag

• delete_tag (destructive) — Delete a repository tag

• get_tag_signature (read-only) — Get the X.509 signature of a signed tag (404 if unsigned)

users (7 tools) — Default: Active

• get_users (read-only) — Get GitLab user details by usernames

• get_user (read-only) — Get user details by ID

• whoami (read-only) — Get current authenticated user details

• list_events (read-only) — List events for the authenticated user (before/after: YYYY-MM-DD)

• get_project_events (read-only) — List events for a project (before/after: YYYY-MM-DD)

• upload_markdown — Upload a file for use in markdown content

• download_attachment (read-only) — Download an uploaded file from a project (images returned as base64; use local_path to save to disk)

workitems (18 tools) — Opt-in (GITLAB_TOOLSETS=workitems)

• get_work_item (read-only) — Get a work item with full details including status, hierarchy, type, and widgets

• list_work_items (read-only) — List work items with filters (type, state, search, assignees, labels)

• create_work_item — Create a work item (issue, task, incident, epic, etc.) with full field support

• update_work_item — Update a work item (title, description, labels, assignees, state, parent, custom fields, etc.)

• convert_work_item_type — Convert a work item to a different type

• list_work_item_statuses (read-only) — List available statuses for a work item type (Premium/Ultimate)

• list_custom_field_definitions (read-only) — List custom field definitions for a work item type

• move_work_item — Move a work item to a different project

• list_work_item_notes (read-only) — List notes and discussions on a work item

• create_work_item_note — Add a note to a work item (supports Markdown, internal notes, threads)

• list_work_item_emoji_reactions (read-only) — List all emoji reactions on a work item

• list_work_item_note_emoji_reactions (read-only) — List all emoji reactions on a work item note (comment, thread, or thread reply)

• create_work_item_emoji_reaction — Add an emoji reaction to a work item (e.g. thumbsup, rocket, eyes)

• delete_work_item_emoji_reaction (destructive) — Remove an emoji reaction from a work item

• create_work_item_note_emoji_reaction — Add an emoji reaction to a work item note (comment, thread, or thread reply)

• delete_work_item_note_emoji_reaction (destructive) — Remove an emoji reaction from a work item note (comment, thread, or thread reply)

• get_timeline_events (read-only) — List timeline events for an incident

• create_timeline_event — Create a timeline event on an incident

webhooks (3 tools) — Opt-in (GITLAB_TOOLSETS=webhooks)

• list_webhooks (read-only) — List webhooks for a project or group

• list_webhook_events (read-only) — List recent webhook events (past 7 days)

• get_webhook_event (read-only) — Get full details of a specific webhook event

search (3 tools) — Opt-in (GITLAB_TOOLSETS=search)

• search_code (read-only) — Search for code across all projects (requires advanced search or Zoekt)

• search_project_code (read-only) — Search for code within a specific project (requires advanced search or Zoekt)

• search_group_code (read-only) — Search for code within a specific group (requires advanced search or Zoekt)

variables (10 tools) — Opt-in (GITLAB_TOOLSETS=variables)

• list_project_variables (read-only) — List CI/CD variables for a project

• get_project_variable (read-only) — Get a single CI/CD variable from a project

• create_project_variable — Create a CI/CD variable for a project

• update_project_variable — Update an existing CI/CD variable in a project

• delete_project_variable (destructive) — Delete a CI/CD variable from a project

• list_group_variables (read-only) — List CI/CD variables for a group

• get_group_variable (read-only) — Get a single CI/CD variable from a group

• create_group_variable — Create a CI/CD variable for a group

• update_group_variable — Update an existing CI/CD variable in a group

• delete_group_variable (destructive) — Delete a CI/CD variable from a group

dependency_proxy (4 tools) — Opt-in (GITLAB_TOOLSETS=dependency_proxy)

• get_dependency_proxy_settings (read-only) — Get dependency proxy settings for a group

• update_dependency_proxy_settings — Update dependency proxy settings for a group (enable/disable, credentials for authenticated Docker Hub pulls)

• list_dependency_proxy_blobs (read-only) — List cached dependency proxy blobs for a group

• purge_dependency_proxy_cache (destructive) — Schedule purge of all cached dependency proxy blobs for a group

runners (6 tools) — Opt-in (GITLAB_TOOLSETS=runners)

• list_runners (read-only) — List GitLab CI/CD runners. Can be scoped to all runners, a specific project, or a specific group. Supports filtering by type, status, and tags.

• get_runner (read-only) — Get detailed information about a specific GitLab CI/CD runner including platform, architecture, tags, version, IP address, and last contact time.

• pause_runner — Pause (disable) a GitLab CI/CD runner so it will not pick up new jobs. The runner remains registered but inactive.

• resume_runner — Resume (re-enable) a previously paused GitLab CI/CD runner so it can start picking up jobs again.

• delete_runner (destructive) — Permanently delete a GitLab CI/CD runner. This action is irreversible — the runner must be re-registered to be used again.

• list_runner_jobs (read-only) — List jobs that have been executed by a specific GitLab CI/CD runner. Useful for auditing runner activity and debugging job failures.

meta (2 tools) — Default: Active

• discover_tools (read-only) — Discover and activate additional tool categories at runtime for the current session.

• execute_graphql (read-only / mutation) — Execute custom GraphQL queries and mutations against GitLab.

Complete Tool Inventory (218 Tools)

1. merge_merge_request (destructive) - Merge a merge request

2. approve_merge_request - Approve a merge request

3. unapprove_merge_request - Unapprove a merge request

4. get_merge_request_approval_state (read-only) - Get merge request approval details including approvers

5. get_merge_request_conflicts (read-only) - Get the conflicts of a merge request

6. list_merge_request_pipelines (read-only) - List pipelines for a merge request with pagination

7. execute_graphql (read-only) - Execute a GitLab GraphQL query

8. create_or_update_file - Create or update a file in a GitLab project

9. search_repositories (read-only) - Search for GitLab projects

10. create_repository - Create a new GitLab project

11. create_group - Create new group or subgroup

12. get_file_contents (read-only) - Get contents of a file or directory from a GitLab project

13. push_files (destructive) - Push multiple files in a single commit

14. create_issue - Create a new issue

15. create_merge_request - Create a new merge request

16. fork_repository - Fork a project to your account or specified namespace

17. create_branch - Create a new branch

18. get_branch (read-only) - Get branch details (commit, protection status)

19. list_branches (read-only) - List branches in project with search filter

20. delete_branch (destructive) - Delete branch from project

21. list_protected_branches (read-only) - List protected branches in a project, supports search filter

22. get_protected_branch (read-only) - Get details of a single protected branch (access levels, force push settings)

23. protect_branch (destructive) - Protect a repository branch (set push/merge/unprotect access levels)

24. unprotect_branch (destructive) - Remove protection from a previously protected branch

25. update_default_branch (destructive) - Change the default branch of a project

26. get_merge_request (read-only) - Get details of a merge request (mergeRequestIid or branchName required). Set include_summaries=true for deployment/commit/approval summaries

27. get_merge_request_diffs (read-only) - Get the changes/diffs of a merge request (mergeRequestIid or branchName required)

28. list_merge_request_changed_files (read-only) - List changed file paths in a merge request without diff content (mergeRequestIid or branchName required)

29. list_merge_request_diffs (read-only) - List merge request diffs with pagination (mergeRequestIid or branchName required)

30. get_merge_request_file_diff (read-only) - Get diffs for specific files from a merge request (mergeRequestIid or branchName required)

31. list_merge_request_versions (read-only) - List all versions of a merge request

32. get_merge_request_version (read-only) - Get a specific version of a merge request

33. get_branch_diffs (read-only) - Get diffs between two branches or commits

34. update_merge_request - Update a merge request (mergeRequestIid or branchName required)

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

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

37. resolve_merge_request_thread - Resolve a thread on a merge request

38. mr_discussions (read-only) - List discussion items for a merge request

39. delete_merge_request_discussion_note (destructive) - Delete a discussion note on a merge request

40. update_merge_request_discussion_note - Update a discussion note on a merge request

41. create_merge_request_discussion_note - Add a new discussion note to an existing merge request thread

42. create_merge_request_note - Add a new note to a merge request

43. delete_merge_request_note (destructive) - Delete an existing merge request note

44. get_merge_request_note (read-only) - Get a specific note for a merge request

45. get_merge_request_notes (read-only) - List notes for a merge request

46. update_merge_request_note - Modify an existing merge request note

47. get_draft_note (read-only) - Get a single draft note from a merge request

48. list_draft_notes (read-only) - List draft notes for a merge request

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

50. update_draft_note - Update an existing draft note

51. delete_draft_note (destructive) - Delete a draft note

52. publish_draft_note - Publish a single draft note

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

54. list_merge_request_emoji_reactions (read-only) - List all emoji reactions on a merge request

55. list_merge_request_note_emoji_reactions (read-only) - List all emoji reactions on a merge request note. Pass discussion_id for discussion thread replies.

56. create_merge_request_emoji_reaction - Add an emoji reaction to a merge request (e.g. thumbsup, rocket, eyes)

57. delete_merge_request_emoji_reaction (destructive) - Remove an emoji reaction from a merge request

58. create_merge_request_note_emoji_reaction - Add an emoji reaction to a merge request note. Pass discussion_id for discussion thread replies.

59. delete_merge_request_note_emoji_reaction (destructive) - Remove an emoji reaction from a merge request note. Pass discussion_id for discussion thread replies.

60. update_issue_note - Modify an existing issue thread note

61. create_issue_note - Add a note to an issue, optionally replying to a discussion thread

62. list_issue_emoji_reactions (read-only) - List all emoji reactions on an issue

63. list_issue_note_emoji_reactions (read-only) - List all emoji reactions on an issue note. Pass discussion_id for discussion thread replies.

64. create_issue_emoji_reaction - Add an emoji reaction to an issue (e.g. thumbsup, rocket, eyes)

65. delete_issue_emoji_reaction (destructive) - Remove an emoji reaction from an issue

66. create_issue_note_emoji_reaction - Add an emoji reaction to an issue note. Pass discussion_id for discussion thread replies.

67. delete_issue_note_emoji_reaction (destructive) - Remove an emoji reaction from an issue note. Pass discussion_id for discussion thread replies.

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

69. my_issues (read-only) - List issues assigned to the authenticated user

70. get_issue (read-only) - Get details of a specific issue. Returns a slim milestone by default; set full_response=true for the complete milestone object

71. update_issue - Update an issue. Returns a slim confirmation by default; set full_response=true for the complete updated issue object

72. update_issue_description_patch - Apply a patch (search/replace or unified diff) to an issue description. Reduces token usage by allowing small changes without sending the full description. Supports dry_run to preview changes and create_note to summarize updates.

73. delete_issue (destructive) - Delete an issue

74. list_todos (read-only) - List GitLab to-do items for the current user

75. mark_todo_done - Mark a GitLab to-do item as done

76. mark_all_todos_done - Mark all pending GitLab to-do items as done for the current user

77. list_issue_links (read-only) - List all issue links for a specific issue

78. list_issue_discussions (read-only) - List discussions for an issue

79. get_issue_link (read-only) - Get a specific issue link

80. create_issue_link - Create an issue link between two issues

81. delete_issue_link (destructive) - Delete an issue link

82. list_namespaces (read-only) - List all namespaces (users and groups) available to the current user. Filter by kind='group' for groups only.

83. get_namespace (read-only) - Get details of a namespace (user or group) by ID or path. Groups are namespaces with kind='group'.

84. verify_namespace (read-only) - Verify if a namespace path exists. Use parent_id to scope the check to a specific parent namespace — required for nested namespaces where the same path may exist under different parents.

85. get_project (read-only) - Get details of a specific project

86. list_projects (read-only) - List projects accessible by the current user

87. update_project - Update project settings such as description, visibility, default branch, and feature access levels

88. list_project_members (read-only) - List members of a GitLab project

89. list_labels (read-only) - List labels for a project

90. get_label (read-only) - Get a single label from a project

91. create_label - Create a new label in a project

92. update_label - Update an existing label in a project

93. delete_label (destructive) - Delete a label from a project

94. list_group_projects (read-only) - List projects in a group

95. list_wiki_pages (read-only) - List wiki pages in a project

96. get_wiki_page (read-only) - Get details of a specific wiki page

97. create_wiki_page - Create a wiki page in a project

98. update_wiki_page - Update a wiki page in a project

99. delete_wiki_page (destructive) - Delete a wiki page from a project

100. list_group_wiki_pages (read-only) - List wiki pages in a group

101. get_group_wiki_page (read-only) - Get details of a specific group wiki page

102. create_group_wiki_page - Create a wiki page in a group

103. update_group_wiki_page - Update a wiki page in a group

104. delete_group_wiki_page (destructive) - Delete a wiki page from a group

105. get_repository_tree (read-only) - List files and directories in a repository

106. list_pipelines (read-only) - List pipelines with filtering options

107. get_pipeline (read-only) - Get details of a specific pipeline

108. list_deployments (read-only) - List deployments with filtering options

109. get_deployment (read-only) - Get details of a specific deployment

110. list_environments (read-only) - List environments in a project

111. get_environment (read-only) - Get details of a specific environment

112. list_pipeline_jobs (read-only) - List all jobs in a specific pipeline

113. list_pipeline_trigger_jobs (read-only) - List trigger jobs (bridges) in a pipeline

114. get_pipeline_job (read-only) - Get details of a GitLab pipeline job number

115. get_pipeline_job_output (read-only) - Get the output/trace of a pipeline job with optional pagination

116. validate_ci_lint (read-only) - Validate provided GitLab CI/CD YAML content for a project

117. validate_project_ci_lint (read-only) - Validate an existing .gitlab-ci.yml configuration for a project

118. list_ci_catalog_resources (read-only) - List GitLab CI/CD Catalog resources/components visible to the user

119. get_ci_catalog_resource (read-only) - Get details for a GitLab CI/CD Catalog resource, including versions and components

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

121. retry_pipeline - Retry a failed or canceled pipeline

122. cancel_pipeline - Cancel a running pipeline

123. play_pipeline_job - Run a manual pipeline job

124. retry_pipeline_job - Retry a failed or canceled pipeline job

125. cancel_pipeline_job - Cancel a running pipeline job

126. list_job_artifacts (read-only) - List artifact files in a job's archive

127. download_job_artifacts (read-only) - Download job artifact archive (zip) and save to a local path

128. get_job_artifact_file (read-only) - Get content of a single file from a job's artifacts

129. list_merge_requests (read-only) - List merge requests (without project_id: user's MRs; with project_id: project MRs)

130. list_milestones (read-only) - List milestones with filtering options

131. get_milestone (read-only) - Get details of a specific milestone

132. create_milestone - Create a new milestone

133. edit_milestone - Edit an existing milestone

134. delete_milestone (destructive) - Delete a milestone

135. get_milestone_issue (read-only) - Get issues associated with a specific milestone

136. get_milestone_merge_requests (read-only) - Get merge requests associated with a specific milestone

137. promote_milestone - Promote a milestone to the next stage

138. get_milestone_burndown_events (read-only) - Get burndown events for a specific milestone

139. list_group_milestones (read-only) - List group milestones with filtering options

140. get_group_milestone (read-only) - Get details of a specific group milestone

141. create_group_milestone - Create a new group milestone

142. edit_group_milestone - Edit an existing group milestone

143. delete_group_milestone (destructive) - Delete a group milestone

144. get_group_milestone_issue (read-only) - Get issues associated with a specific group milestone

145. get_group_milestone_merge_requests (read-only) - Get merge requests associated with a specific group milestone

146. get_group_milestone_burndown_events (read-only) - Get burndown events for a specific group milestone

147. get_users (read-only) - Get GitLab user details by usernames

148. get_user (read-only) - Get user details by ID

149. whoami (read-only) - Get current authenticated user details

150. list_commits (read-only) - List repository commits with filtering options

151. get_commit (read-only) - Get details of a specific commit

152. get_commit_diff (read-only) - Get changes/diffs of a specific commit

153. get_file_blame (read-only) - Get git blame for a file at a given ref. Each entry maps a contiguous range of source lines to the commit that last changed them (id, author, authored_date, message). Use range_start/range_end to limit blame to specific lines.

154. list_commit_statuses (read-only) - List statuses for a commit

155. create_commit_status - Create or update the status of a commit

156. list_group_iterations (read-only) - List group iterations with filtering options

157. upload_markdown - Upload a file for use in markdown content

158. download_attachment (read-only) - Download an uploaded file from a project (images returned as base64; use local_path to save to disk)

159. health_check (read-only) - Verify server status and authentication

160. list_events (read-only) - List events for the authenticated user (before/after: YYYY-MM-DD)

161. get_project_events (read-only) - List events for a project (before/after: YYYY-MM-DD)

162. list_releases (read-only) - List all releases for a project

163. get_release (read-only) - Get a release by tag name

164. create_release - Create a new release

165. update_release - Update an existing release

166. delete_release (destructive) - Delete a release (does not delete the tag)

167. create_release_evidence - Create release evidence (Premium/Ultimate)

168. download_release_asset (read-only) - Download a release asset file by direct asset path

169. list_tags (read-only) - List repository tags for a project

170. get_tag (read-only) - Get a repository tag by name

171. create_tag - Create a new repository tag

172. delete_tag (destructive) - Delete a repository tag

173. get_tag_signature (read-only) - Get the X.509 signature of a signed tag (404 if unsigned)

174. get_work_item (read-only) - Get a work item with full details including status, hierarchy, type, and widgets

175. list_work_items (read-only) - List work items with filters (type, state, search, assignees, labels)

176. create_work_item - Create a work item (issue, task, incident, epic, etc.) with full field support

177. update_work_item - Update a work item (title, description, labels, assignees, state, parent, custom fields, etc.)

178. convert_work_item_type - Convert a work item to a different type

179. list_work_item_statuses (read-only) - List available statuses for a work item type (Premium/Ultimate)

180. list_custom_field_definitions (read-only) - List custom field definitions for a work item type

181. move_work_item - Move a work item to a different project

182. list_work_item_notes (read-only) - List notes and discussions on a work item

183. create_work_item_note - Add a note to a work item (supports Markdown, internal notes, threads)

184. list_work_item_emoji_reactions (read-only) - List all emoji reactions on a work item

185. list_work_item_note_emoji_reactions (read-only) - List all emoji reactions on a work item note (comment, thread, or thread reply)

186. create_work_item_emoji_reaction - Add an emoji reaction to a work item (e.g. thumbsup, rocket, eyes)

187. delete_work_item_emoji_reaction (destructive) - Remove an emoji reaction from a work item

188. create_work_item_note_emoji_reaction - Add an emoji reaction to a work item note (comment, thread, or thread reply)

189. delete_work_item_note_emoji_reaction (destructive) - Remove an emoji reaction from a work item note (comment, thread, or thread reply)

190. get_timeline_events (read-only) - List timeline events for an incident

191. create_timeline_event - Create a timeline event on an incident

192. list_webhooks (read-only) - List webhooks for a project or group

193. list_webhook_events (read-only) - List recent webhook events (past 7 days)

194. get_webhook_event (read-only) - Get full details of a specific webhook event

195. search_code (read-only) - Search for code across all projects (requires advanced search or Zoekt)

196. search_project_code (read-only) - Search for code within a specific project (requires advanced search or Zoekt)

197. search_group_code (read-only) - Search for code within a specific group (requires advanced search or Zoekt)

198. list_project_variables (read-only) - List CI/CD variables for a project

199. get_project_variable (read-only) - Get a single CI/CD variable from a project

200. create_project_variable - Create a CI/CD variable for a project

201. update_project_variable - Update an existing CI/CD variable in a project

202. delete_project_variable (destructive) - Delete a CI/CD variable from a project

203. list_group_variables (read-only) - List CI/CD variables for a group

204. get_group_variable (read-only) - Get a single CI/CD variable from a group

205. create_group_variable - Create a CI/CD variable for a group

206. update_group_variable - Update an existing CI/CD variable in a group

207. delete_group_variable (destructive) - Delete a CI/CD variable from a group

208. get_dependency_proxy_settings (read-only) - Get dependency proxy settings for a group

209. update_dependency_proxy_settings - Update dependency proxy settings for a group (enable/disable, credentials for authenticated Docker Hub pulls)

210. list_dependency_proxy_blobs (read-only) - List cached dependency proxy blobs for a group

211. purge_dependency_proxy_cache (destructive) - Schedule purge of all cached dependency proxy blobs for a group

212. list_runners (read-only) - List GitLab CI/CD runners. Can be scoped to all runners, a specific project, or a specific group. Supports filtering by type, status, and tags.

213. get_runner (read-only) - Get detailed information about a specific GitLab CI/CD runner including platform, architecture, tags, version, IP address, and last contact time.

214. pause_runner - Pause (disable) a GitLab CI/CD runner so it will not pick up new jobs. The runner remains registered but inactive.

215. resume_runner - Resume (re-enable) a previously paused GitLab CI/CD runner so it can start picking up jobs again.

216. delete_runner (destructive) - Permanently delete a GitLab CI/CD runner. This action is irreversible — the runner must be re-registered to be used again.

217. list_runner_jobs (read-only) - List jobs that have been executed by a specific GitLab CI/CD runner. Useful for auditing runner activity and debugging job failures.

218. discover_tools (read-only) - Discover and activate additional tool categories for this session. Available categories: merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, users, workitems, webhooks, search, variables, dependency_proxy, runners. Already-active categories are listed in the response.

How Custom Tools Are Built

This server is designed to be easily extensible. Every tool follows a strict 4-file pipeline:

1. schemas.ts                 Define input parameters using Zod (descriptions guide the LLM)
       │
       ▼
2. tools/registry.ts          Register tool in allTools, assign toolset, and categorize permissions
       │
       ▼
3. index.ts                   Implement GitLab API fetch logic and route in handleToolCall()
       │
       ▼
4. scripts/generate-tool-docs.ts   Add toolset metadata for documentation generation & type checking

Verification Checklist

When implementing or modifying tools:

1. Run npm run build to verify TypeScript compilation.

2. Run npm run test:schema to validate input parsing.

3. Run npm run check:skill-sync to ensure agent skill definitions match tools/registry.ts.

Development & Verification

# Install local dependencies
npm install

# Compile TypeScript
npm run build

# Run schema and validation tests
npm run test:schema

# Verify skill definitions stay synchronized with the registry
npm run check:skill-sync

# Verify runtime dependencies
npm run check:runtime-deps

# Run full test suite
npm test

Author & Acknowledgments

• Maintained by: aryannverse (@aryannverse)

• Based on: @zereight/mcp-gitlab

• License: MIT License