Allows an AI client to manage GitLab projects, merge requests, issues, pipelines, and perform global searches.
Also known as crunchtools/mcp-gitlab, mcp-gitlab, mcp-gitlab-crunchtools
- Stars
- 2
- Tools
- 27
- Downloads, 30 days
- 904
- Latest version
- 0.4.1
- Last commit
- Nov 12, 2026
- License
- AGPL-3.0
What is GitLab MCP?
GitLab is an MCP server. Allows an AI client to manage GitLab projects, merge requests, issues, pipelines, and perform global searches. It exposes 27 tools, such as list_projects, get_project, list_project_branches.
Summary generated from the project's README
About GitLab MCP server
Managing GitLab repositories and development workflows from within an AI client is what this MCP server enables. It allows developers to interact with projects, groups, merge requests, issues, and CI/CD pipelines through a local connection. The server works with gitlab.com, enterprise instances, or self-hosted setups by configuring a custom URL and providing a personal access token via environment variables.
Running locally via stdio, the server ensures your API token stays on your machine. It provides specific tools like list_projects, create_merge_request, and get_pipeline_log to automate routine tasks. Users can also perform global or project-specific searches using search_global and search_project. The implementation uses Pydantic for input validation and is available as a Python package, a CLI command, or a container image built on a minimal Hummingbird Python base.
What you can do with it
- 1Automate issue and comment managementAn AI client can create new issues or add comments to existing ones to track bugs.
- 2Monitor CI/CD pipeline healthDevelopers can ask an AI to identify failed pipelines and retrieve the specific job logs for debugging.
- 3Review and manage merge requestsYou can use the assistant to list open merge requests or fetch the code diffs for a specific change.
- 4Search across GitLab resourcesA developer can find specific code snippets or resources across the entire GitLab instance.
Written from the project's README. Every use case is checked against a quote from it.
How to install GitLab MCP
Formats verified 10 Nov 2026Install GitLab MCP in Claude Code
$ claude mcp add mcp-gitlab -- uvx mcp-gitlab-crunchtoolsInstall GitLab MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-gitlab": {
"command": "uvx",
"args": [
"mcp-gitlab-crunchtools"
]
}
}
}Install GitLab MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-gitlab": {
"type": "stdio",
"command": "uvx",
"args": [
"mcp-gitlab-crunchtools"
]
}
}
}Install GitLab MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-gitlab": {
"command": "uvx",
"args": [
"mcp-gitlab-crunchtools"
]
}
}
}Install GitLab MCP in Codex
~/.codex/config.toml
[mcp_servers.mcp-gitlab] command = "uvx" args = ["mcp-gitlab-crunchtools"]
Install GitLab MCP in Gemini CLI
~/.gemini/settings.json
{
"mcpServers": {
"mcp-gitlab": {
"command": "uvx",
"args": [
"mcp-gitlab-crunchtools"
]
}
}
}GitLab MCP tools 27
Detected from the READMElist_projectsget_projectlist_project_branchesget_project_branchlist_project_commitslist_groupsget_grouplist_group_projectslist_merge_requestsget_merge_requestcreate_merge_requestupdate_merge_request
| list_projects | — | |
| get_project | — | |
| list_project_branches | — | |
| get_project_branch | — | |
| list_project_commits | — | |
| list_groups | — | |
| get_group | — | |
| list_group_projects | — | |
| list_merge_requests | — | |
| get_merge_request | — | |
| create_merge_request | — | |
| update_merge_request | — |
Show all 27 toolsShow fewer tools
list_mr_notescreate_mr_noteget_mr_changeslist_issuesget_issuecreate_issueupdate_issuelist_issue_notescreate_issue_notelist_pipelinesget_pipelinelist_pipeline_jobsget_job_logsearch_globalsearch_project
| list_mr_notes | — | |
| create_mr_note | — | |
| get_mr_changes | — | |
| list_issues | — | |
| get_issue | — | |
| create_issue | — | |
| update_issue | — | |
| list_issue_notes | — | |
| create_issue_note | — | |
| list_pipelines | — | |
| get_pipeline | — | |
| list_pipeline_jobs | — | |
| get_job_log | — | |
| search_global | — | |
| search_project | — |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablecrunchtools/mcp-gitlab is public and reachablegithub.com/crunchtools/mcp-gitlab ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Sigstore attestation for mcp-gitlab-crunchtoolspypi.org/project/mcp-gitlab-crunchtools/ ↗Pass
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-12github.com/crunchtools/mcp-gitlab ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcp-gitlab-crunchtoolsPass
- No critical advisory in the package or its dependencies65 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model27 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP 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 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-gitlabbuilt on Hummingbird Python base image
Naming Convention
| Component | Name |
|---|---|
| GitHub repo | crunchtools/mcp-gitlab |
| Container | quay.io/crunchtools/mcp-gitlab |
| Python package (PyPI) | mcp-gitlab-crunchtools |
| CLI command | mcp-gitlab-crunchtools |
| Module import | mcp_gitlab_crunchtools |
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 (7 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 MR
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-crunchtools
With pip
pip install mcp-gitlab-crunchtools
With Container
podman run -e GITLAB_TOKEN=your_token \
quay.io/crunchtools/mcp-gitlab
Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
GITLAB_TOKEN |
Yes | — | Personal Access Token |
GITLAB_URL |
No | https://gitlab.com |
GitLab instance URL |
SSL_CERT_FILE |
No | — | Custom CA bundle path, for self-hosted GitLab with an internal CA |
GITLAB_SSL_VERIFY |
No | true |
Set false to disable TLS verification (not recommended) |
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-crunchtools - Expiration: Set an appropriate date (90 days recommended)
- Scopes: Select scopes based on your needs
- Name:
-
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
- Copy the token immediately (starts with
Add to Claude Code
claude mcp add mcp-gitlab-crunchtools \
--env GITLAB_TOKEN=your_token_here \
-- uvx mcp-gitlab-crunchtools
For 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-crunchtools
For 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-gitlab
Usage 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 sync
Run Tests
uv run pytest
Lint and Type Check
uv run ruff check src tests
uv run mypy src
Build 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
GitLab MCP questions
How do I add GitLab MCP to Claude Code?
Run claude mcp add mcp-gitlab -- uvx mcp-gitlab-crunchtools in your terminal. Add --scope user to make it available in every project.
How do I add GitLab MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does GitLab MCP provide?
It exposes 27 tools, including list_projects, get_project, list_project_branches, get_project_branch, list_project_commits.
Does this work with self-hosted GitLab instances?
Yes, it works with gitlab.com, self-hosted, or enterprise instances via a configurable URL.
How is my GitLab token secured?
The token is held as a SecretStr to prevent accidental logging and is only passed via environment variables.
What permissions do I need to grant the token?
You can use the 'read_api' scope for read-only access or the 'api' scope for full access including creating and updating resources.
Can I run this in a container?
Yes, a containerized version is available via Quay.io.