mcp-gitlab-crunchtools
An MCP server that exposes ~60 tools for reading and managing GitLab projects, merge requests, issues, CI/CD pipelines, repositories, and more through the GitLab REST API, with token held as a SecretStr and Pydantic-validated inputs.
Projects & groups – list/search projects and groups, get details, create or permanently delete a project (with visibility, namespace, README init), and list group projects including subgroups.
Branches & commits – list/get branches, create and delete branches, list project commits filtered by date, path, or ref, and compare two branches/tags/commits.
Repository files – list the repository tree (optionally recursive), read a file, create or update files with text or base64 content, and commit messages.
Merge requests – list/filter MRs, get details and diffs, create and update them (title, description, labels, assignees, reviewers, milestone, close/reopen), and read or add notes and threaded discussions.
Safe merging – merge an MR only at a required head
sha(refusing drafts, conflicts, closed MRs, or a moved head), or set merge-when-pipeline-succeeds; check CI first via MR pipelines withshaandstatus.Issues – list/filter by state, labels, milestone, assignee, get, create, update (including confidentiality and open/close), plus list and add comments.
Pipelines & jobs – list/get pipelines, trigger new pipelines on a ref, retry, cancel, or delete pipelines; list pipeline jobs, fetch job logs, retry, cancel, or delete jobs.
Search – global search across projects, issues, MRs, milestones, commits, blobs, notes, users, etc., and project-scoped search.
Labels – list, create, update, and delete project labels with colors, priorities, and descriptions.
Users – get the authenticated user, list users (active, by username or search), and fetch a user by ID.
Releases & milestones – list/get/create releases and tags, list/create/update project milestones with dates and state changes.
Wiki & snippets – list/get/create wiki pages in multiple formats, and list/create project snippets.
Provides tools for interacting with GitLab instances, enabling management of projects, groups, merge requests, issues, pipelines, and search across GitLab resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-gitlab-crunchtools What merge requests are waiting for my review?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP GitLab CrunchTools
A secure MCP (Model Context Protocol) server for GitLab projects, merge requests, issues, pipelines, and search. Works with any GitLab instance (gitlab.com, self-hosted, or enterprise).
Overview
This MCP server is designed to be:
Secure by default - documented threat model (see SECURITY.md), Pydantic input validation, and the API token held as a
SecretStrto prevent accidental loggingNo third-party services - Runs locally via stdio, your API token never leaves your machine
Multi-instance - Works with gitlab.com, self-hosted GitLab, or enterprise instances via configurable URL
Cross-platform - Works on Linux, macOS, and Windows
Automatically updated - GitHub Actions monitor for CVEs and update dependencies
Containerized - Available at
quay.io/crunchtools/mcp-gitlabbuilt on Hummingbird Python base image
Related MCP server: gitlab-mcp-server
Naming Convention
Component | Name |
GitHub repo | |
Container |
|
Python package (PyPI) |
|
CLI command |
|
Module import |
|
Why Hummingbird?
The container image is built on the Hummingbird Python base image from Project Hummingbird, which provides:
Minimal CVE exposure - Built with a minimal package set, dramatically reducing the attack surface
Regular updates - Security patches are applied promptly
Optimized for Python - Pre-configured Python environment with uv package manager
Production-ready - Proper signal handling and non-root user defaults
Features
Project Management (5 tools)
list_projects- List projects with filtering and searchget_project- Get project details by ID or pathlist_project_branches- List repository branchesget_project_branch- Get a single branchlist_project_commits- List commits with date/path filtering
Group Management (3 tools)
list_groups- List groups with filteringget_group- Get group details by ID or pathlist_group_projects- List projects in a group (with subgroup support)
Merge Requests (11 tools)
list_merge_requests- List MRs by state, labels, milestoneget_merge_request- Get MR detailscreate_merge_request- Create a new MRupdate_merge_request- Update MR title, description, state, assigneeslist_mr_notes- List comments on an MRcreate_mr_note- Add a comment to an MRget_mr_changes- Get the diff for an MRlist_mr_discussions- List threaded discussions on an MRcreate_mr_discussion- Start a discussion on an MRmerge_merge_request- Merge an MR at a required headsha, or set it to merge when its pipeline succeeds; refuses drafts, conflicts and a moved headget_mr_pipelines- List an MR's pipelines with theshaandstatusof each, to check CI before merging
Issues (6 tools)
list_issues- List issues by state, labels, milestone, assigneeget_issue- Get issue detailscreate_issue- Create a new issueupdate_issue- Update issue title, description, state, labelslist_issue_notes- List comments on an issuecreate_issue_note- Add a comment to an issue
Pipelines (4 tools)
list_pipelines- List CI/CD pipelines with status filteringget_pipeline- Get pipeline detailslist_pipeline_jobs- List jobs in a pipelineget_job_log- Get job log output
Search (2 tools)
search_global- Search across all accessible GitLab resourcessearch_project- Search within a specific project
Installation
With uvx (Recommended)
uvx mcp-gitlab-crunchtoolsWith pip
pip install mcp-gitlab-crunchtoolsWith Container
podman run -e GITLAB_TOKEN=your_token \
quay.io/crunchtools/mcp-gitlabConfiguration
Environment Variables
Variable | Required | Default | Description |
| Yes | — | Personal Access Token |
| No |
| GitLab instance URL |
| No | — | Custom CA bundle path, for self-hosted GitLab with an internal CA |
| No |
| Set |
Creating a GitLab Personal Access Token
Navigate to Access Tokens
Go to https://gitlab.com/-/user_settings/personal_access_tokens
Or: Avatar > Preferences > Access Tokens
Create a Custom Token
Name:
mcp-gitlab-crunchtoolsExpiration: Set an appropriate date (90 days recommended)
Scopes: Select scopes based on your needs
Scope Selection
Scope
Access Level
Capabilities
read_apiRead-only
List/view projects, issues, MRs, pipelines
apiFull access
All features including create/update
Copy and Store Token
Copy the token immediately (starts with
glpat-)Store securely in a password manager
Add to Claude Code
claude mcp add mcp-gitlab-crunchtools \
--env GITLAB_TOKEN=your_token_here \
-- uvx mcp-gitlab-crunchtoolsFor self-hosted GitLab:
claude mcp add mcp-gitlab-crunchtools \
--env GITLAB_TOKEN=your_token_here \
--env GITLAB_URL=https://gitlab.example.com \
-- uvx mcp-gitlab-crunchtoolsFor the container version:
claude mcp add mcp-gitlab-crunchtools \
--env GITLAB_TOKEN=your_token_here \
-- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlabUsage Examples
List Your Projects
User: List my GitLab projects
Assistant: [calls list_projects with membership=true]View Merge Requests
User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]Create an Issue
User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]Check Pipeline Status
User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]Search Code
User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]Security
This server was designed with security as a primary concern. See SECURITY.md for:
Threat model and attack vectors
Defense in depth architecture
Token handling best practices
Input validation rules
Audit logging
Key Security Features
Token Protection
Stored as SecretStr (never accidentally logged)
Environment variable only (never in files or args)
Sanitized from all error messages
Input Validation
Pydantic models for all inputs
Allowlist character validation for project/group IDs
Path traversal prevention
API Hardening
HTTPS enforcement (except localhost)
TLS certificate validation
Request timeouts (30s)
Response size limits (10MB)
Automated CVE Scanning
GitHub Actions scan dependencies weekly
Container security scanning with Trivy
CodeQL analysis for Python
Development
Setup
git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv syncRun Tests
uv run pytestLint and Type Check
uv run ruff check src tests
uv run mypy srcBuild Container
podman build -t mcp-gitlab .License
AGPL-3.0-or-later
Contributing
Contributions welcome! Please read SECURITY.md before submitting security-related changes.
Links
Available Tools
65 toolscancel_job_toolCancel Job ToolC
Cancel a running CI/CD job.
Inputs: job_id (required), project_id (required). Returns: object
cancel_pipeline_toolCancel Pipeline ToolC
Cancel a running CI/CD pipeline.
Inputs: project_id (required), pipeline_id (required). Returns: object
compare_branches_toolCompare Branches ToolBRead-only
Compare two branches, tags, or commits.
Inputs: to_ref (required), from_ref (required), project_id (required), straight. Returns: object
create_branch_toolCreate Branch ToolC
Create a new branch in a GitLab repository.
Inputs: ref (required), branch (required), project_id (required). Returns: object
create_file_toolCreate File ToolC
Create a new file in a GitLab repository.
Inputs: branch (required), content (required), file_path (required), project_id (required), +2 more. Returns: object
create_issue_note_toolCreate Issue Note ToolB
Create a note (comment) on an issue.
Inputs: body (required), issue_iid (required), project_id (required). Returns: object
create_issue_toolCreate Issue ToolC
Create a new issue in a GitLab project.
Inputs: title (required), project_id (required), labels, description, +3 more. Returns: object
create_label_toolCreate Label ToolC
Create a new label in a GitLab project.
Inputs: name (required), color (required), project_id (required), priority, +1 more. Returns: object
create_merge_request_toolCreate Merge Request ToolC
Create a new merge request.
Inputs: title (required), project_id (required), source_branch (required), target_branch (required), +6 more. Returns: object
create_milestone_toolCreate Milestone ToolC
Create a new milestone in a GitLab project.
Inputs: title (required), project_id (required), due_date, start_date, +1 more. Returns: object
create_mr_discussion_toolCreate Mr Discussion ToolC
Create a new discussion on a merge request.
Inputs: body (required), project_id (required), merge_request_iid (required). Returns: object
create_mr_note_toolCreate Mr Note ToolC
Create a note (comment) on a merge request.
Inputs: body (required), project_id (required), merge_request_iid (required). Returns: object
create_pipeline_toolCreate Pipeline ToolC
Create (trigger) a new CI/CD pipeline.
Inputs: project_id (required), ref. Returns: object
create_project_toolCreate Project ToolC
Create a new GitLab project.
Inputs: name (required), visibility, description, namespace_id, +1 more. Returns: object
create_release_toolCreate Release ToolC
Create a new release for a GitLab project.
Inputs: tag_name (required), project_id (required), ref, name, +2 more. Returns: object
create_snippet_toolCreate Snippet ToolB
Create a new snippet in a GitLab project.
Inputs: title (required), content (required), file_name (required), project_id (required), +2 more. Returns: object
create_wiki_page_toolCreate Wiki Page ToolC
Create a new wiki page in a GitLab project.
Inputs: title (required), content (required), project_id (required), format. Returns: object
delete_branch_toolDelete Branch ToolC
Delete a branch from a GitLab repository.
Inputs: branch (required), project_id (required). Returns: object
delete_job_toolDelete Job ToolB
Delete a CI/CD job's artifacts and trace log.
Inputs: job_id (required), project_id (required). Returns: object
delete_label_toolDelete Label ToolB
Delete a label from a GitLab project.
Inputs: label_id (required), project_id (required). Returns: object
delete_pipeline_toolDelete Pipeline ToolB
Delete a CI/CD pipeline and all its jobs permanently.
Inputs: project_id (required), pipeline_id (required). Returns: object
delete_project_toolDelete Project ToolC
Delete a GitLab project permanently.
Inputs: project_id (required). Returns: object
get_current_user_toolGet Current User ToolARead-only
Get the currently authenticated GitLab user.
Inputs: no named parameters. Returns: object
get_file_toolGet File ToolARead-only
Get a file from a GitLab repository.
Returns file metadata and content (base64 encoded).
Inputs: file_path (required), project_id (required), ref. Returns: object
get_group_toolGet Group ToolBRead-only
Get GitLab group details by ID or path.
Inputs: group_id (required), with_projects. Returns: object
get_issue_toolGet Issue ToolCRead-only
Get a single issue by its IID.
Inputs: issue_iid (required), project_id (required). Returns: object
get_job_log_toolGet Job Log ToolBRead-only
Get the log (trace) output of a CI/CD job.
Inputs: job_id (required), project_id (required). Returns: object
get_merge_request_toolGet Merge Request ToolBRead-only
Get a single merge request by its IID.
Inputs: project_id (required), merge_request_iid (required). Returns: object
get_mr_changes_toolGet Mr Changes ToolCRead-only
Get the changes (diff) for a merge request.
Inputs: project_id (required), merge_request_iid (required). Returns: object
get_mr_pipelines_toolGet Mr Pipelines ToolARead-only
List the pipelines of a merge request, newest first.
Each pipeline carries the sha it ran on and its status (success, failed, running, ...), so you can confirm the MR head passed CI before merging.
Inputs: project_id (required), merge_request_iid (required), page, per_page. Returns: object
get_pipeline_toolGet Pipeline ToolBRead-only
Get a single CI/CD pipeline by ID.
Inputs: project_id (required), pipeline_id (required). Returns: object
get_project_branch_toolGet Project Branch ToolBRead-only
Get a single repository branch.
Inputs: branch (required), project_id (required). Returns: object
get_project_toolGet Project ToolBRead-only
Get GitLab project details by ID or path.
Inputs: project_id (required). Returns: object
get_release_toolGet Release ToolARead-only
Get a single release by tag name.
Inputs: tag_name (required), project_id (required). Returns: object
get_user_toolGet User ToolBRead-only
Get a specific GitLab user by ID.
Inputs: user_id (required). Returns: object
get_wiki_page_toolGet Wiki Page ToolCRead-only
Get a single wiki page by slug.
Inputs: slug (required), project_id (required). Returns: object
list_group_projects_toolList Group Projects ToolCRead-only
List projects within a GitLab group.
Inputs: group_id (required), page, sort, search, +4 more. Returns: object
list_groups_toolList Groups ToolBRead-only
List GitLab groups accessible by the API token.
Inputs: page, sort, owned, search, +3 more. Returns: object
list_issue_notes_toolList Issue Notes ToolBRead-only
List notes (comments) on an issue.
Inputs: issue_iid (required), project_id (required), page, sort, +2 more. Returns: object
list_issues_toolList Issues ToolCRead-only
List issues for a GitLab project.
Inputs: project_id (required), page, sort, state, +6 more. Returns: object
list_labels_toolList Labels ToolCRead-only
List labels for a GitLab project.
Inputs: project_id (required), page, search, per_page. Returns: object
list_merge_requests_toolList Merge Requests ToolCRead-only
List merge requests for a GitLab project.
Inputs: project_id (required), page, sort, state, +5 more. Returns: object
list_milestones_toolList Milestones ToolBRead-only
List milestones for a GitLab project.
Inputs: project_id (required), page, state, search, +1 more. Returns: object
list_mr_discussions_toolList Mr Discussions ToolBRead-only
List discussions (threaded comments) on a merge request.
Discussions include inline code review comments with file position data.
Inputs: project_id (required), merge_request_iid (required), page, per_page. Returns: object
list_mr_notes_toolList Mr Notes ToolCRead-only
List notes (comments) on a merge request.
Inputs: project_id (required), merge_request_iid (required), page, sort, +2 more. Returns: object
list_pipeline_jobs_toolList Pipeline Jobs ToolCRead-only
List jobs for a CI/CD pipeline.
Inputs: project_id (required), pipeline_id (required), page, scope, +1 more. Returns: object
list_pipelines_toolList Pipelines ToolCRead-only
List CI/CD pipelines for a GitLab project.
Inputs: project_id (required), ref, page, sort, +3 more. Returns: object
list_project_branches_toolList Project Branches ToolCRead-only
List repository branches for a GitLab project.
Inputs: project_id (required), page, search, per_page. Returns: object
list_project_commits_toolList Project Commits ToolBRead-only
List repository commits for a GitLab project.
Inputs: project_id (required), page, path, since, +3 more. Returns: object
list_projects_toolList Projects ToolBRead-only
List GitLab projects accessible by the API token.
Inputs: page, sort, owned, search, +4 more. Returns: object
list_releases_toolList Releases ToolBRead-only
List releases for a GitLab project.
Inputs: project_id (required), page, sort, order_by, +1 more. Returns: object
list_repository_tree_toolList Repository Tree ToolCRead-only
List repository tree (files and directories).
Inputs: project_id (required), ref, page, path, +2 more. Returns: object
list_snippets_toolList Snippets ToolBRead-only
List snippets for a GitLab project.
Inputs: project_id (required), page, per_page. Returns: object
list_users_toolList Users ToolCRead-only
List GitLab users.
Inputs: page, active, search, per_page, +1 more. Returns: object
list_wiki_pages_toolList Wiki Pages ToolCRead-only
List wiki pages for a GitLab project.
Inputs: project_id (required), page, per_page, with_content. Returns: object
merge_merge_request_toolMerge Merge Request ToolA
Merge a merge request, or set it to merge when its pipeline succeeds.
sha is required and must be the full commit ID of the source branch head (the MR's "sha" field): GitLab merges only if the head is still that commit, so nothing pushed after review can slip in. A draft, a conflict, a closed MR or a moved head is refused without merging. Check CI first with get_mr_pipelines.
Inputs: sha (required), project_id (required), merge_request_iid (required), squash, +2 more. Returns: object
retry_job_toolRetry Job ToolC
Retry a specific failed CI/CD job.
Inputs: job_id (required), project_id (required). Returns: object
retry_pipeline_toolRetry Pipeline ToolA
Retry all failed jobs in a CI/CD pipeline.
Inputs: project_id (required), pipeline_id (required). Returns: object
search_global_toolSearch Global ToolCRead-only
Search across all GitLab resources accessible by the token.
Inputs: search (required), page, scope, per_page. Returns: object
search_project_toolSearch Project ToolCRead-only
Search within a specific GitLab project.
Inputs: search (required), project_id (required), page, scope, +1 more. Returns: object
update_file_toolUpdate File ToolC
Update an existing file in a GitLab repository.
Inputs: branch (required), content (required), file_path (required), project_id (required), +2 more. Returns: object
update_issue_toolUpdate Issue ToolC
Update an existing issue.
Inputs: issue_iid (required), project_id (required), title, labels, +5 more. Returns: object
update_label_toolUpdate Label ToolC
Update an existing label in a GitLab project.
Inputs: label_id (required), project_id (required), color, new_name, +2 more. Returns: object
update_merge_request_toolUpdate Merge Request ToolC
Update an existing merge request.
Inputs: project_id (required), merge_request_iid (required), title, labels, +7 more. Returns: object
update_milestone_toolUpdate Milestone ToolC
Update an existing milestone.
Inputs: project_id (required), milestone_id (required), title, due_date, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 65 tools
The vast majority of tools target a distinct resource+action pair (create_issue vs update_issue vs list_issue_notes), so selection is usually unambiguous. A few boundaries blur: list_mr_notes_tool vs list_mr_discussions_tool overlap conceptually, search_global_tool vs search_project_tool differ only by scope, and merge_merge_request_tool partially overlaps update_merge_request_tool which can also change MR state.
Nearly every tool follows a clean verb_noun_tool pattern, which makes the surface very predictable. Minor deviations exist: the noun is sometimes 'mr' and sometimes 'merge_request' (list_mr_notes_tool vs list_merge_requests_tool), and merge_merge_request_tool doubles the verb awkwardly.
At 65 tools this is well past the 25+ heavy threshold and even exceeds the 50-tool extreme marker, so the surface is hard for an agent to hold in context. The breadth is partly justified by GitLab's genuinely large API, but grouping (e.g. pipelines/jobs, notes/discussions) could have been consolidated.
Coverage is broad across projects, issues, MRs, pipelines/jobs, repo files, branches, labels, users, releases, milestones, wiki, snippets, search and commits. Gaps remain: no delete_issue, no wiki page update/delete, no release/milestone/snippet deletion, and no tags, members, or MR approval operations, which are common lifecycle needs.
Maintenance
Related MCP Connectors
Unofficial GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
GitLab Public MCP — wraps the GitLab REST API v4 (public endpoints, no auth)
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceMCP server for interacting with GitLab API, supporting both self-hosted instances and gitlab.com. Provides tools for managing issues, merge requests, code review, pipelines, milestones, releases, search, and file access.MIT
- AlicenseAqualityDmaintenanceEnables interacting with GitLab repositories, merge requests, and code through natural language using MCP. Supports authentication with personal access tokens or OAuth2, and provides tools for listing projects, reading repository code, and analyzing merge request lifetimes.103MIT
- FlicenseNot gradedqualityDmaintenanceExposes the GitLab REST API to MCP clients for managing projects, issues, merge requests, repositories, and CI/CD pipelines. It is multi-tenant, allowing each user to authenticate with their own token and instance URL.-
- FlicenseAqualityDmaintenanceEnables LLMs to interact with GitLab via MCP, providing access to issues, merge requests, pipelines, and repository files for browsing, searching, and reading details.19-