GitLab MCP server
Commit Nov 14, 2026Lets an AI client search GitLab repositories, review merge requests, manage issues, and summarize team activity.
Also known as ttpears/gitlab-mcp
- Stars
- 13
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Nov 14, 2026
- License
- MIT
What is GitLab MCP?
GitLab lets an AI client search GitLab repositories, review merge requests, manage issues, and summarize team activity.
Summary generated from the project's README
About GitLab MCP server
Managing GitLab repositories and tracking team progress from within an AI client is what this server enables. Developers can use it to search for projects, groups, and users, or to perform deeper technical tasks like inspecting code via file contents and resolving repository paths. It works with both GitLab.com and self-managed instances through stdio or Streamable HTTP connections.
To set it up locally, you need Node.js 22 or later and a GitLab personal access token. For read-only access, you provide a GITLAB_READ_TOKEN, while a GITLAB_TOKEN allows for write operations like creating issues or updating merge requests. The server provides 69 distinct tools and 8 workflow prompts to handle everything from reviewing merge request diffs and CI pipeline results to summarizing group activity and identifying review bottlenecks.
This tool is designed for engineers using local clients like Claude Desktop or VS Code, as well as those deploying shared remote servers via Docker. It respects your existing GitLab permissions and token scopes, ensuring the AI can only interact with resources the authenticated user can access.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
GITLAB_READ_TOKENGITLAB_URL
| Name | Description | |
|---|---|---|
| GITLAB_READ_TOKEN | — | |
| GITLAB_URL | — |
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablettpears/gitlab-mcp is public and reachablegithub.com/ttpears/gitlab-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-31github.com/ttpears/gitlab-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGitLab MCP Server
A community Model Context Protocol server that lets AI clients search GitLab, read repositories, review merge requests, manage issues, and summarize team activity. Supports GitLab.com and self-managed GitLab through stdio and Streamable HTTP.
This project is independent of GitLab Inc. It does not require GitLab Duo. Individual tools remain subject to your GitLab version, tier, enabled features, token scopes, and role.
Start locally
Requires Node.js 22 or later. CI covers Node.js 22 and 24; the container uses Node.js 24.
- Create a GitLab personal access token with
read_apifor reads orapifor reads and writes. The token can only access resources its owner is allowed to use. - Add this server to your client's MCP configuration. Replace the token locally; keep the resulting file out of version control.
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["-y", "@ttpears/gitlab-mcp-server@4.0.0"],
"env": {
"GITLAB_URL": "https://gitlab.com",
"GITLAB_READ_TOKEN": "glpat-replace-locally"
}
}
}
}
- Restart or reconnect the client. Ask it to call
get_current_user, thensearch_projectswith{"searchTerm":"your-project","first":5}.
For writes, replace GITLAB_READ_TOKEN with GITLAB_TOKEN and use an api-scoped token. Setting both variables is a startup error. Stdio is the default; it communicates over stdin/stdout and does not open a listening port.
Choose a setup
| Use case | Setup |
|---|---|
| Claude Code, Claude Desktop, VS Code, or another local client | Client installation |
| Claude Desktop bundle | Download gitlab-mcp-community-4.0.0.mcpb from the 4.0.0 release |
| LibreChat with each user's PAT | LibreChat guide and YAML example |
| Shared remote server with GitLab sign-in | OAuth setup |
| Docker or a reverse proxy | Deployment and operations |
| Existing installation | Upgrade to 4.0 |
For a local HTTP smoke test without a shared token:
docker run --rm --name gitlab-mcp \
-p 127.0.0.1:8008:8008 \
-e GITLAB_URL=https://gitlab.com \
ghcr.io/ttpears/gitlab-mcp:4.0.0
Connect an MCP client to http://localhost:8008/ and send Authorization: Bearer <your-GitLab-PAT> on every request. curl http://localhost:8008/health checks liveness. The published image currently targets Linux amd64. Configure HTTPS and user authentication before remote use; see the deployment guide.
What you can do
The server exposes 69 tools and 8 workflow prompts. The tool reference lists every tool, its input parameters, defaults, and write classification.
| Task | Start with |
|---|---|
| Find projects, groups, users, issues, or merge requests | search_projects, search_groups, search_users, search_issues, search_merge_requests |
| Identify a path and inspect code | resolve_path, browse_repository, get_file_content |
| Review a change and its CI results | get_merge_request_context, get_merge_request_diffs, get_merge_request_pipelines, get_pipeline_jobs |
| Triage and update work | get_issue_context, create_issue, update_issue, create_note, update_merge_request |
| Work with planning and notifications | list_milestones, list_iterations, list_work_items, list_my_todos |
| Summarize activity and review delays | analytics_user_summary, analytics_group_summary, analytics_review_bottlenecks |
| Manage group achievements | list_achievements, create_achievement, award_achievement |
| Discover instance-specific API capabilities | get_available_queries, get_type_fields |
Try: “Find open bugs assigned to me,” “Review MR !42 in group/project,” or “Summarize this group's activity since Monday.” See workflows and pagination for exact tool-call examples and prompt names.
Read before sharing a server
GITLAB_TOKENis a fallback for reads and writes.GITLAB_READ_TOKENis a fallback for reads only. A shared fallback exposes that account's accessible data to callers using it.- With neither fallback set, each operation needs user credentials through an HTTP PAT, OAuth, or
userCredentials. - Host pinning, finite resource limits, and restrictions on custom GraphQL/REST tools are enabled by default. Tool annotations are client hints; GitLab permissions and the server's credential checks enforce access.
fetchAll: truefetches up tofirstitems. For complete results, keep following each connection'spageInfo.endCursorwhilehasNextPageis true.
See authentication and security for credential precedence, OAuth consent, encrypted Redis storage, and access boundaries.
Documentation
- Installation and client configuration
- Authentication and security
- Deployment and operations
- Workflows, results, and pagination
- Environment variable reference
- Complete tool reference
- Troubleshooting
- Upgrading to 4.0
- Contributing and architecture
- Changelog · Releases · Issue tracker
Field notes: Two session bugs that broke my GitLab MCP server.
Licensed under MIT.
GitLab MCP questions
What permissions do I need for the access token?
You need a personal access token with 'read_api' scope for read-only access, or 'api' scope for both read and write access.
Can I use this with self-managed GitLab instances?
Yes, the server supports both GitLab.com and self-managed GitLab installations.
How many tools are available in this server?
The server provides 69 different tools and 8 workflow prompts for various tasks.