An MCP server that lets you interact with GitLab projects, code, collaboration, and CI/CD through natural language tool calls.
Projects & Groups: list, create, delete, and inspect GitLab projects and groups, including branches, commits, and group memberships.
Merge Requests: list, view, create, update, comment on, and get diffs/discussions for merge requests.
Issues: list, view, create, update, comment on, and manage labels/assignees/milestones for issues.
Pipelines & Jobs: list, create, retry, cancel, and delete pipelines; view and manage CI/CD jobs and job logs.
Search: search across all GitLab resources or within a specific project (code, issues, MRs, wiki, etc.).
Repository Management: browse repository trees, read/create/update files, create/delete branches, and compare branches/tags/commits.
Labels & Milestones: create, update, list, and delete labels and milestones for projects.
Users & Current User: get authenticated user details and list/look up GitLab users.
Releases: view, create, and retrieve project releases by tag.
Wiki & Snippets: list, view, create wiki pages, and manage 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.
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).
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 SecretStr to prevent accidental logging
No 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-gitlab built on Hummingbird Python base image
Related MCP server: gitlab-mcp-server
Component | Name |
GitHub repo | |
Container |
|
Python package (PyPI) |
|
CLI command |
|
Module import |
|
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
list_projects - List projects with filtering and search
get_project - Get project details by ID or path
list_project_branches - List repository branches
get_project_branch - Get a single branch
list_project_commits - List commits with date/path filtering
list_groups - List groups with filtering
get_group - Get group details by ID or path
list_group_projects - List projects in a group (with subgroup support)
list_merge_requests - List MRs by state, labels, milestone
get_merge_request - Get MR details
create_merge_request - Create a new MR
update_merge_request - Update MR title, description, state, assignees
list_mr_notes - List comments on an MR
create_mr_note - Add a comment to an MR
get_mr_changes - Get the diff for an MR
list_issues - List issues by state, labels, milestone, assignee
get_issue - Get issue details
create_issue - Create a new issue
update_issue - Update issue title, description, state, labels
list_issue_notes - List comments on an issue
create_issue_note - Add a comment to an issue
list_pipelines - List CI/CD pipelines with status filtering
get_pipeline - Get pipeline details
list_pipeline_jobs - List jobs in a pipeline
get_job_log - Get job log output
search_global - Search across all accessible GitLab resources
search_project - Search within a specific project
uvx mcp-gitlab-crunchtoolspip install mcp-gitlab-crunchtoolspodman run -e GITLAB_TOKEN=your_token \
quay.io/crunchtools/mcp-gitlabVariable | 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 |
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-crunchtools
Expiration: Set an appropriate date (90 days recommended)
Scopes: Select scopes based on your needs
Scope Selection
Scope | Access Level | Capabilities |
| Read-only | List/view projects, issues, MRs, pipelines |
| Full access | All features including create/update |
Copy and Store Token
Copy the token immediately (starts with glpat-)
Store securely in a password manager
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-gitlabUser: List my GitLab projects
Assistant: [calls list_projects with membership=true]User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]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
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
git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv syncuv run pytestuv run ruff check src tests
uv run mypy srcpodman build -t mcp-gitlab .AGPL-3.0-or-later
Contributions welcome! Please read SECURITY.md before submitting security-related changes.
Cancel a running CI/CD job.
Inputs: job_id (required), project_id (required). Returns: object
Cancel a running CI/CD pipeline.
Inputs: project_id (required), pipeline_id (required). Returns: object
Compare two branches, tags, or commits.
Inputs: to_ref (required), from_ref (required), project_id (required), straight. Returns: object
Create a new branch in a GitLab repository.
Inputs: ref (required), branch (required), project_id (required). Returns: object
Create a new file in a GitLab repository.
Inputs: branch (required), content (required), file_path (required), project_id (required), +2 more. Returns: object
Create a note (comment) on an issue.
Inputs: body (required), issue_iid (required), project_id (required). Returns: object
Create a new issue in a GitLab project.
Inputs: title (required), project_id (required), labels, description, +3 more. Returns: object
Create a new label in a GitLab project.
Inputs: name (required), color (required), project_id (required), priority, +1 more. Returns: object
Create a new merge request.
Inputs: title (required), project_id (required), source_branch (required), target_branch (required), +6 more. Returns: object
Create a new milestone in a GitLab project.
Inputs: title (required), project_id (required), due_date, start_date, +1 more. Returns: object
Create a new discussion on a merge request.
Inputs: body (required), project_id (required), merge_request_iid (required). Returns: object
Create a note (comment) on a merge request.
Inputs: body (required), project_id (required), merge_request_iid (required). Returns: object
Create (trigger) a new CI/CD pipeline.
Inputs: project_id (required), ref. Returns: object
Create a new GitLab project.
Inputs: name (required), visibility, description, namespace_id, +1 more. Returns: object
Create a new release for a GitLab project.
Inputs: tag_name (required), project_id (required), ref, name, +2 more. Returns: object
Create a new snippet in a GitLab project.
Inputs: title (required), content (required), file_name (required), project_id (required), +2 more. Returns: object
Create a new wiki page in a GitLab project.
Inputs: title (required), content (required), project_id (required), format. Returns: object
Delete a branch from a GitLab repository.
Inputs: branch (required), project_id (required). Returns: object
Delete a CI/CD job's artifacts and trace log.
Inputs: job_id (required), project_id (required). Returns: object
Delete a label from a GitLab project.
Inputs: label_id (required), project_id (required). Returns: object
Delete a CI/CD pipeline and all its jobs permanently.
Inputs: project_id (required), pipeline_id (required). Returns: object
Delete a GitLab project permanently.
Inputs: project_id (required). Returns: object
Get the currently authenticated GitLab user.
Inputs: no named parameters. Returns: object
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 GitLab group details by ID or path.
Inputs: group_id (required), with_projects. Returns: object
Get a single issue by its IID.
Inputs: issue_iid (required), project_id (required). Returns: object
Get the log (trace) output of a CI/CD job.
Inputs: job_id (required), project_id (required). Returns: object
Get a single merge request by its IID.
Inputs: project_id (required), merge_request_iid (required). Returns: object
Get the changes (diff) for a merge request.
Inputs: project_id (required), merge_request_iid (required). Returns: object
Get a single CI/CD pipeline by ID.
Inputs: project_id (required), pipeline_id (required). Returns: object
Get a single repository branch.
Inputs: branch (required), project_id (required). Returns: object
Get GitLab project details by ID or path.
Inputs: project_id (required). Returns: object
Get a single release by tag name.
Inputs: tag_name (required), project_id (required). Returns: object
Get a specific GitLab user by ID.
Inputs: user_id (required). Returns: object
Get a single wiki page by slug.
Inputs: slug (required), project_id (required). Returns: object
List projects within a GitLab group.
Inputs: group_id (required), page, sort, search, +4 more. Returns: object
List GitLab groups accessible by the API token.
Inputs: page, sort, owned, search, +3 more. Returns: object
List notes (comments) on an issue.
Inputs: issue_iid (required), project_id (required), page, sort, +2 more. Returns: object
List issues for a GitLab project.
Inputs: project_id (required), page, sort, state, +6 more. Returns: object
List labels for a GitLab project.
Inputs: project_id (required), page, search, per_page. Returns: object
List merge requests for a GitLab project.
Inputs: project_id (required), page, sort, state, +5 more. Returns: object
List milestones for a GitLab project.
Inputs: project_id (required), page, state, search, +1 more. Returns: object
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 notes (comments) on a merge request.
Inputs: project_id (required), merge_request_iid (required), page, sort, +2 more. Returns: object
List jobs for a CI/CD pipeline.
Inputs: project_id (required), pipeline_id (required), page, scope, +1 more. Returns: object
List CI/CD pipelines for a GitLab project.
Inputs: project_id (required), ref, page, sort, +3 more. Returns: object
List repository branches for a GitLab project.
Inputs: project_id (required), page, search, per_page. Returns: object
List repository commits for a GitLab project.
Inputs: project_id (required), page, path, since, +3 more. Returns: object
List GitLab projects accessible by the API token.
Inputs: page, sort, owned, search, +4 more. Returns: object
List releases for a GitLab project.
Inputs: project_id (required), page, sort, order_by, +1 more. Returns: object
List repository tree (files and directories).
Inputs: project_id (required), ref, page, path, +2 more. Returns: object
List snippets for a GitLab project.
Inputs: project_id (required), page, per_page. Returns: object
List GitLab users.
Inputs: page, active, search, per_page, +1 more. Returns: object
List wiki pages for a GitLab project.
Inputs: project_id (required), page, per_page, with_content. Returns: object
Retry a specific failed CI/CD job.
Inputs: job_id (required), project_id (required). Returns: object
Retry all failed jobs in a CI/CD pipeline.
Inputs: project_id (required), pipeline_id (required). Returns: object
Search across all GitLab resources accessible by the token.
Inputs: search (required), page, scope, per_page. Returns: object
Search within a specific GitLab project.
Inputs: search (required), project_id (required), page, scope, +1 more. Returns: object
Update an existing file in a GitLab repository.
Inputs: branch (required), content (required), file_path (required), project_id (required), +2 more. Returns: object
Update an existing issue.
Inputs: issue_iid (required), project_id (required), title, labels, +5 more. Returns: object
Update an existing label in a GitLab project.
Inputs: label_id (required), project_id (required), color, new_name, +2 more. Returns: object
Update an existing merge request.
Inputs: project_id (required), merge_request_iid (required), title, labels, +7 more. Returns: object
Update an existing milestone.
Inputs: project_id (required), milestone_id (required), title, due_date, +3 more. Returns: object
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 63 tools
Most tools target a distinct resource and action, and descriptions clearly distinguish closely related operations such as pipeline vs. job retry/cancel/delete. Minor overlap exists between notes and discussions on merge requests, and between current-user and user-listing tools, but an agent can generally select correctly.
Names consistently use snake_case with a verb_noun_tool pattern, making the surface predictable. There are small inconsistencies such as `list_mr_notes_tool` using `mr` while other tools spell out `merge_request`, and occasional noun-first forms like `search_global_tool`.
Sixty-three tools is very heavy for a single MCP server and risks overwhelming an agent's selection process. While GitLab is broad, the set could be better grouped or scoped into narrower servers or workflows.
Coverage is extensive across projects, repositories, issues, merge requests, pipelines, labels, wiki, snippets, releases, and search. Notable gaps remain, especially merging a merge request, deleting files, and full lifecycle operations for wiki pages, snippets, releases, and milestones.
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.
