GitLab MCP Server
GitLab MCP Server lets AI clients search, read, review, and manage GitLab projects, issues, merge requests, CI, todos, and activity via MCP over stdio or Streamable HTTP.
Search and inspect projects, groups, users, issues, merge requests, labels, notes, milestones, iterations, work items, group members, broadcast messages, and repository files.
Review merge requests with context bundles, diffs, commits, pipelines, jobs, reviewers/approvals, notes, and time tracking.
Create, update, and delete issues/notes; create/update merge requests; retry/cancel pipelines; manage todos; and administer broadcast messages where permissions allow.
Summarize user or group activity and surface review bottlenecks with analytics tools.
Run custom GraphQL queries and arbitrary REST read/write escape-hatch calls for uncovered endpoints.
Use per-request user credentials or configured fallback tokens, with read-only and write-gated operations.
Provides comprehensive GitLab integration with search across projects, issues, merge requests, users, and groups; code exploration and file browsing; issue and merge request management (create, update); and support for custom GraphQL queries with automatic schema discovery. Supports both GitLab.com and self-hosted instances.
Enables execution of custom GraphQL queries against GitLab's API with automatic schema introspection and discovery of available operations.
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., "@GitLab MCP Server search for open issues in the 'web-app' project"
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.
GitLab 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.
Related MCP server: GitLab MR MCP
Choose a setup
Use case | Setup |
Claude Code, Claude Desktop, VS Code, or another local client | |
Claude Desktop bundle | Download |
LibreChat with each user's PAT | |
Shared remote server with GitLab sign-in | |
Docker or a reverse proxy | |
Existing installation |
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.0Connect 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 |
|
Identify a path and inspect code |
|
Review a change and its CI results |
|
Triage and update work |
|
Work with planning and notifications |
|
Summarize activity and review delays |
|
Manage group achievements |
|
Discover instance-specific API capabilities |
|
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
Field notes: Two session bugs that broke my GitLab MCP server.
Licensed under MIT.
Available Tools
69 toolsanalytics_group_summaryGroup Activity SummaryARead-onlyIdempotent
Aggregated activity summary for an entire group (optionally including subgroups) over a time window — totals by action type (pushes, MRs opened/merged, comments, approvals), with breakdowns by project, by contributor, and by day. Use this to answer "what did this team do" without fanning out across list_project_events yourself.
Inputs: group (required), since (required), until, maxEvents, +4 more.
analytics_review_bottlenecksReview BottlenecksARead-onlyIdempotent
Aggregate open (non-draft) merge requests across a group or project to surface review bottlenecks. Returns per-reviewer queue stats, age-bucket histogram, and the stalest MRs by updatedAt. MRs with no reviewer assigned are bucketed under "(unassigned)".
Inputs: group, maxMRs, project, topStalest, +2 more.
analytics_user_summaryUser Activity SummaryARead-onlyIdempotent
Aggregated activity summary for a user over a time window — totals by action type (pushes, MRs opened/merged, comments, approvals), breakdown by project and by day. Use this instead of list_user_events when you want counts rather than a raw event feed.
Inputs: user (required), since (required), until, maxEvents, +1 more.
award_achievementAward AchievementA
Award an achievement to a GitLab username. Multiple awards to the same user are allowed. Requires group Maintainer/Owner. GitLab notifies the recipient, who may need to accept before it appears on their profile.
Inputs: username (required), achievementId (required), awardMessage, userCredentials.
browse_repositoryBrowse RepositoryBRead-onlyIdempotent
Browse repository files and folders - essential for exploring codebase structure
Inputs: projectPath (required), ref, path, userCredentials.
create_achievementCreate AchievementA
Create a group achievement with name and optional description. Requires group Maintainer/Owner and enabled Achievements. Set avatars in GitLab UI; file uploads are not supported by this tool.
Inputs: name (required), group (required), description, userCredentials.
create_broadcast_messageCreate Broadcast MessageA
Create a GitLab broadcast message. Requires administrator privileges on the GitLab instance.
Inputs: message (required), font, color, theme, +7 more.
create_issueCreate IssueA
Create a new issue in a GitLab project (requires user authentication with write permissions)
Inputs: title (required), projectPath (required), description, userCredentials. Returns: id, iid, title, webUrl
create_merge_requestCreate Merge RequestB
Create a new merge request in a GitLab project (requires user authentication with write permissions)
Inputs: title (required), projectPath (required), sourceBranch (required), targetBranch (required), +2 more. Returns: id, iid, title, webUrl
create_noteCreate NoteB
Add a comment/note to an issue or merge request (requires user authentication)
Inputs: iid (required), body (required), projectPath (required), noteableType (required), +2 more.
delete_achievementDelete AchievementADestructiveIdempotent
Delete a group achievement and every related awarded or revoked instance. Destructive; requires group Maintainer/Owner.
Inputs: achievementId (required), userCredentials.
delete_broadcast_messageDelete Broadcast MessageADestructiveIdempotent
Delete a GitLab broadcast message by ID. Requires administrator privileges.
Inputs: id (required), userCredentials.
delete_issueDelete IssueADestructiveIdempotent
Delete a GitLab issue. Requires a user token with permission to delete issues in the project (typically the issue author or a maintainer).
Inputs: iid (required), projectPath (required), userCredentials.
delete_noteDelete NoteADestructiveIdempotent
Delete a comment (note) on a GitLab issue or merge request. Requires a user token belonging to the note author or a maintainer.
Inputs: noteId (required), userCredentials.
execute_custom_queryCustom GraphQL QueryA
Execute custom GraphQL queries for complex filtering (e.g., issues with assigneeUsernames: ["user"], labelName: ["bug"]). Use this for structured filtering by assignee/author/labels when search tools return 0 results. Use pagination and limit complexity to avoid timeouts.
Inputs: query (required), variables, requiresWrite, userCredentials.
execute_rest_readCustom REST ReadARead-onlyIdempotent
Execute an arbitrary GET request against the GitLab REST API at /api/v4. Open-ended escape hatch for read endpoints not covered by a dedicated tool — e.g. /projects/:id/repository/files, /projects/:id/pipelines/:pipeline_id/test_report, /admin/*. Provide the path beginning with "/" (no host, no /api/v4 prefix) and an optional query object. For writes, use execute_rest_write.
Inputs: path (required), query, userCredentials.
execute_rest_writeCustom REST WriteADestructive
Execute an arbitrary POST/PUT/PATCH/DELETE request against the GitLab REST API at /api/v4. Open-ended escape hatch for write endpoints not covered by a dedicated tool. Destructive — DELETE is permitted, so check the path before invoking. For reads, use execute_rest_read.
Inputs: path (required), method (required), body, query, +1 more.
get_available_queriesAvailable QueriesCRead-onlyIdempotent
Get list of available GraphQL queries and mutations from the GitLab schema
Inputs: userCredentials.
get_broadcast_messageGet Broadcast MessageARead-onlyIdempotent
Get a specific GitLab broadcast message by ID.
Inputs: id (required), userCredentials.
get_current_userCurrent UserARead-onlyIdempotent
Get information about the current authenticated GitLab user
Inputs: userCredentials. Returns: id, name, username
get_file_contentFile ContentCRead-onlyIdempotent
Get the content of a specific file from a GitLab repository - crucial for code analysis
Inputs: filePath (required), projectPath (required), ref, userCredentials.
get_group_projectsGroup ProjectsCRead-onlyIdempotent
List projects inside a GitLab group (optionally filter by search term)
Inputs: fullPath (required), after, first, searchTerm, +1 more.
get_issue_contextGet Issue ContextARead-onlyIdempotent
Bundle issue body, all notes (paginated up to maxNotes), related merge requests (mentioning), closing merge requests, linked issues (relates_to/blocks/is_blocked_by) into a single call. Use this instead of fanning out across get_issues + get_notes + search_merge_requests when investigating an issue.
Inputs: iid (required), projectPath (required), maxNotes, userCredentials, +1 more.
get_issuesProject IssuesCRead-onlyIdempotent
Get issues from a specific GitLab project (read-only)
Inputs: projectPath (required), sort, after, first, +2 more. Returns: nodes, hasMore, pageInfo, totalFetched
get_merge_request_commitsMR CommitsARead-onlyIdempotent
Get commits for a merge request (excluding merge commits), with commit count and details
Inputs: iid (required), projectPath (required), after, first, +2 more.
get_merge_request_contextGet Merge Request ContextARead-onlyIdempotent
Bundle MR body, all notes (paginated up to maxNotes, filtered to non-system by default), commits, pipeline summary, reviewers with approval state, and issues this MR will close into a single call. Use this instead of fanning out across get_merge_requests + get_notes + get_merge_request_commits + get_merge_request_pipelines when investigating an MR.
Inputs: iid (required), projectPath (required), maxNotes, maxCommits, +2 more.
get_merge_request_diffsMR DiffsBRead-onlyIdempotent
Get diff statistics for a merge request, including per-file additions/deletions and diff refs
Inputs: iid (required), projectPath (required), userCredentials.
get_merge_request_pipelinesMR PipelinesBRead-onlyIdempotent
Get CI/CD pipelines for a merge request, including status, duration, and stages
Inputs: iid (required), projectPath (required), after, first, +2 more.
get_merge_request_reviewersMR ReviewersARead-onlyIdempotent
Get approval and reviewer status for a merge request, including who approved and review states
Inputs: iid (required), projectPath (required), userCredentials.
get_merge_requestsMerge RequestsCRead-onlyIdempotent
Get merge requests from a specific GitLab project (read-only)
Inputs: projectPath (required), sort, after, first, +2 more. Returns: nodes, hasMore, pageInfo, totalFetched
get_notesNotes/CommentsBRead-onlyIdempotent
Get notes (comments) on an issue or merge request, including system notes and inline MR comments
Inputs: iid (required), projectPath (required), noteableType (required), after, +3 more.
get_pipeline_jobsPipeline JobsARead-onlyIdempotent
Get jobs for a specific pipeline, including status, stage, duration, and retry/cancel info
Inputs: pipelineIid (required), projectPath (required), after, first, +2 more.
get_projectProject DetailsCRead-onlyIdempotent
Get detailed information about a specific GitLab project (read-only)
Inputs: fullPath (required), userCredentials. Returns: id, name, webUrl, fullPath
get_projectsList ProjectsBRead-onlyIdempotent
List projects accessible to the user (requires authentication to see private projects)
Inputs: sort, after, first, fetchAll, +1 more. Returns: nodes, hasMore, pageInfo, totalFetched
get_project_statisticsProject StatisticsARead-onlyIdempotent
Get aggregate project statistics: open issues/MRs, star/fork counts, storage sizes, commit count, last pipeline status, release count, and language breakdown
Inputs: projectPath (required), userCredentials.
get_time_trackingTime TrackingARead-onlyIdempotent
Get time tracking data (estimate, spent, timelogs) for an issue or merge request
Inputs: iid (required), projectPath (required), resourceType (required), after, +3 more.
get_type_fieldsGraphQL Type FieldsARead-onlyIdempotent
List available fields on a GraphQL type using introspected schema (requires schema to be introspected)
Inputs: typeName (required), userCredentials.
get_user_issuesUser IssuesBRead-onlyIdempotent
Get all issues assigned to a specific user - uses proper GraphQL filtering for reliable results
Inputs: username (required), after, first, state, +3 more.
get_user_merge_requestsUser Merge RequestsCRead-onlyIdempotent
Get merge requests for a specific user (as author or assignee) - uses proper GraphQL filtering
Inputs: username (required), role, after, first, +4 more.
get_work_itemGet Work ItemARead-onlyIdempotent
Fetch a GitLab work item (issue, task, epic, incident, OKR) by global ID. Returns the raw widgets array so epic hierarchy, health status, iteration, milestone, and dates are all visible. Accepts either a numeric id or a full gid (gid://gitlab/WorkItem/123).
Inputs: id (required), userCredentials.
list_achievementsList AchievementsARead-onlyIdempotent
List group achievements with cursor pagination. Requires Achievements to be enabled on the GitLab instance. Optional recipient previews are a single page per achievement; each preview includes pageInfo.
Inputs: group (required), ids, after, first, +3 more.
list_broadcast_messagesList Broadcast MessagesARead-onlyIdempotent
List all GitLab broadcast messages (instance-wide announcements). Read-only.
Inputs: page, perPage, userCredentials.
list_group_membersGroup MembersARead-onlyIdempotent
List group members with access levels, optionally filtered by search term
Inputs: groupPath (required), after, first, search, +2 more.
list_iterationsIterationsARead-onlyIdempotent
List iterations (sprints) for a group with cadence info. Requires GitLab Premium/Ultimate.
Inputs: groupPath (required), after, first, state, +2 more.
list_milestonesMilestonesARead-onlyIdempotent
List milestones for a project or group with progress statistics (total/closed issue counts)
Inputs: fullPath (required), isProject (required), after, first, +5 more.
list_my_eventsMy EventsBRead-onlyIdempotent
List the authenticated user's GitLab activity feed — pushes, MRs, comments, approvals, issue actions. Primary tool for "what did I just do". Requires user authentication.
Inputs: page, sort, after, scope, +5 more.
list_my_todosMy TodosARead-onlyIdempotent
List the authenticated user's GitLab to-do items (notifications about issues, MRs, mentions, reviews requested, etc.). Filter by state, action, target type, or group/project. Requires user authentication.
Inputs: sort, type, after, first, +8 more.
list_project_eventsProject EventsARead-onlyIdempotent
List activity events for a single GitLab project — commits pushed, MRs opened/merged, issues touched, notes added. Accepts project full path or numeric ID.
Inputs: project (required), page, sort, after, +5 more.
list_user_eventsUser EventsARead-onlyIdempotent
List a specific user's public GitLab activity feed by username or numeric ID. Use for tracking what a teammate has been working on.
Inputs: user (required), page, sort, after, +5 more.
list_work_itemsList Work ItemsARead-onlyIdempotent
List work items within a namespace (group or project fullPath). Supports filtering by type (ISSUE, TASK, EPIC, INCIDENT, OBJECTIVE, KEY_RESULT) and state, plus cursor pagination and fetchAll.
Inputs: fullPath (required), sort, after, first, +4 more.
manage_pipelineManage PipelineA
Retry or cancel a CI/CD pipeline (requires user authentication with write permissions)
Inputs: action (required), pipelineIid (required), projectPath (required), userCredentials.
mark_all_todos_doneMark All Todos DoneADestructiveIdempotent
Mark pending to-do items as done for the authenticated user. With no arguments, marks every pending todo. Optional scoping args (groupPath, projectPath, action, type, authorIds, targetId) narrow which todos are marked. Irreversible without per-item restore_todo calls. Returns the actual list of updated todos.
Inputs: type, action, targetId, authorIds, +3 more.
mark_todo_doneMark Todo DoneAIdempotent
Mark a single to-do item as done for the authenticated user. Requires the todo's ID (numeric or full gid://gitlab/Todo/N form) from list_my_todos.
Inputs: todoId (required), userCredentials.
resolve_pathResolve PathBRead-onlyIdempotent
Resolve a GitLab path to either a project or group and list group projects when applicable
Inputs: fullPath (required), after, first, userCredentials.
restore_todoRestore TodoAIdempotent
Restore a previously-marked-done to-do item back to pending state. Accepts the todo's ID (numeric or full gid://gitlab/Todo/N form).
Inputs: todoId (required), userCredentials.
revoke_achievementRevoke AchievementADestructiveIdempotent
Revoke one awarded achievement. Provide either userAchievementId, or group + achievementId + username. Username lookup scans recipient pages and rejects ambiguous repeated awards; use a specific userAchievementId in that case. Requires group Maintainer/Owner.
Inputs: group, username, achievementId, userCredentials, +1 more.
search_gitlabSearch GitLabARead-onlyIdempotent
Text search across GitLab projects and issues (Note: Does not support filtering by assignee/labels - use search_issues for that. MRs cannot be searched globally - use search_merge_requests with username)
Inputs: after, first, fetchAll, searchTerm, +1 more.
search_groupsSearch GroupsCRead-onlyIdempotent
Search for GitLab groups and organizations
Inputs: searchTerm (required), after, first, fetchAll, +1 more.
search_issuesSearch IssuesBRead-onlyIdempotent
Search for issues with text search and/or structured filtering (assignee, author, labels, state). For filtering by assignee/author/labels without text search, leave searchTerm empty.
Inputs: sort, after, first, state, +7 more. Returns: nodes, hasMore, pageInfo, totalFetched
search_labelsSearch LabelsBRead-onlyIdempotent
Search for labels in a project or group, with optional text filtering
Inputs: fullPath (required), isProject (required), after, first, +3 more.
search_merge_requestsSearch Merge RequestsARead-onlyIdempotent
Search merge requests by username (supports "username", "author:username", "assignee:username") or search within a specific project. Note: GitLab does not support global text search for MRs - use projectPath for text searches.
Inputs: searchTerm (required), sort, after, first, +4 more. Returns: nodes, hasMore, pageInfo, totalFetched
search_notesSearch Notes (Comments)ARead-onlyIdempotent
Full-text search across issue and merge request comments. Scope can be global, a project, or a group. NOTE: on self-hosted GitLab, the "notes" search scope requires Advanced Search (Elasticsearch) to be enabled — without it, this endpoint returns an error. search_gitlab does NOT search note bodies; this tool does.
Inputs: search (required), page, scope, perPage, +3 more.
search_projectsSearch ProjectsCRead-onlyIdempotent
Search for GitLab projects by name or description
Inputs: searchTerm (required), after, first, fetchAll, +1 more. Returns: nodes, hasMore, pageInfo, totalFetched
search_usersSearch UsersBRead-onlyIdempotent
Search for GitLab users by username or name - useful for finding team members or contributors
Inputs: searchTerm (required), after, first, fetchAll, +1 more.
update_achievementUpdate AchievementAIdempotent
Update an achievement name or description. Requires group Maintainer/Owner. Provide at least one changed field; an empty description clears it.
Inputs: achievementId (required), name, description, userCredentials.
update_broadcast_messageUpdate Broadcast MessageBIdempotent
Update an existing GitLab broadcast message. Requires administrator privileges.
Inputs: id (required), font, color, theme, +8 more.
update_issueUpdate IssueBIdempotent
Update an issue (title, description, assignees, labels, due date) with schema-aware mutations
Inputs: iid (required), projectPath (required), title, dueDate, +4 more.
update_merge_requestUpdate Merge RequestBIdempotent
Update a merge request (title, description, assignees, reviewers, labels) with schema-aware mutations
Inputs: iid (required), projectPath (required), title, labelNames, +4 more.
update_noteUpdate NoteAIdempotent
Edit the body of an existing comment (note) on a GitLab issue or merge request. Requires a user token belonging to the note author.
Inputs: body (required), noteId (required), userCredentials.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 69 tools
There are several overlapping retrieval paths—get_issues/search_issues/get_user_issues/list_work_items/get_issue_context for issues and analogous merge request tools—plus get_notes vs search_notes and dedicated tools vs execute_rest_read/execute_custom_query. Descriptions generally explain when to use which, so boundaries are recoverable, but the set still invites misselection.
Almost all tools use snake_case verb_noun naming such as get_project, create_issue, delete_note, and search_merge_requests. Minor deviations like analytics_user_summary, execute_rest_read, and mark_all_todos_done are readable and do not break the overall pattern.
69 tools is far beyond a well-scoped MCP surface and includes many specialized, overlapping, and escape-hatch tools. This creates a large selection burden for an agent and is an extreme mismatch for typical usage.
Core issue, merge request, note, pipeline, todo, event, achievement, and broadcast workflows are covered, and generic REST/GraphQL escape hatches prevent total dead ends. However, common GitLab operations like project/group CRUD, label/milestone lifecycle, branches, and file writes lack dedicated tools, so coverage is only partial.
Maintenance
Related MCP Connectors
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Access the GitHub API, enabling file operations, repository management, search functionality, and…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables interaction with GitLab repositories through secure OAuth 2.0 authentication. Supports comprehensive GitLab operations including merge requests, issues, file management, commits, and branch operations through natural language.12 npmMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to interact with GitLab repositories, manage merge requests, review code diffs, post comments, and handle issues directly through natural language.MIT
- FlicenseNot gradedqualityNot gradedmaintenanceEnables AI agents to interact with GitLab repositories, monitor documentation changes, manage issues and merge requests, and search across projects with comprehensive file and commit operations.-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to interact with GitLab for managing projects, branches, issues, and merge requests. It provides tools for searching code and performing file operations like reading and writing directly within repositories.26 npmMIT