gitlab-mcp-lite
Integrates with the GitLab REST API for a single project, providing tools to inspect pipelines and their jobs, list and view issues, list merge requests, create pipelines, play manual jobs, comment on issues, and create merge requests. Write operations support dry-run defaults, and the server can run in read-only mode.
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-lite show me the open merge requests"
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-lite
A small MCP server for the GitLab REST API: pipelines, manual jobs, issues and merge requests of one project.
No runtime dependencies (Python 3.11+ standard library), no setup beyond a token, works with self-hosted GitLab.
Write tools default to dry runs and can be removed entirely with --read-only.
Quick start
export GITLAB_API_KEY=glpat-... # a personal or project access token with the `api` scope
cd your-clone-of-a-gitlab-project
uvx gitlab-mcp-lite check # shows what it resolved and tests the connection
uvx gitlab-mcp-lite config-snippet claudecheck prints the API URL, the project, where the token came from (never the token) and whether GitLab
accepts it. Run it first when something does not work.
Related MCP server: @wanadev/mcp-gitlab
Configuration
Everything is resolved from the environment, a .env file and the git origin remote. First match wins.
Value | Sources, in order | Default |
Token |
| none (required) |
GitLab URL |
| host of the |
Project | the tool's | path of the |
Request timeout |
|
|
Read-only mode |
| off |
In a clone of the project you want to manage, only the token is needed. Outside a clone, set GITLAB_URL and
GITLAB_PROJECT, or pass project per call.
Where to keep the token. Prefer a .env file in the repository root (GITLAB_API_KEY=glpat-..., listed in
.gitignore): the server reads it itself, so it works the same in every client. MCP clients usually start servers
with a trimmed environment, so a variable exported in your shell may not reach the server; if you rely on the
environment, pass it through the client's own env setting. The token is sent only in the PRIVATE-TOKEN header
and is never included in tool results or error messages.
Tools
Tool | Does | Writes |
| status, ref, sha and URL of a pipeline | no |
| jobs of a pipeline (paged) | no |
| issues by | no |
| one issue with description, assignees, milestone | no |
| merge requests by | no |
| create a pipeline for a branch or tag; | yes |
| play a manual job; | yes |
| add a comment to an issue | yes |
| create a merge request; | yes |
Every tool takes an optional project. Lists return compact rows; per_page is 1-100 (default 30) and page
starts at 1. Failures come back as isError results with the reason, so an agent can see what went wrong.
Read-only tools carry readOnlyHint, so clients can skip the approval prompt for them.
Adding it to a client
gitlab-mcp-lite config-snippet <client> prints the block (clients: claude, vscode, codex, cursor,
gemini, generic; options --url, --project, --read-only, --from <path|git-url>). See
docs/clients.md.
claude mcp add gitlab -- uvx gitlab-mcp-liteDevelopment
python -m pip install -e ".[dev]"
ruff check . && mypy && pytestTests use a stand-in transport and a local HTTP server; they need no network and no token.
Releasing
Pushing to main runs the tests on Linux, macOS and Windows and builds the package. If version in
pyproject.toml has no v<version> tag yet, the workflow publishes to PyPI and creates the tag and GitHub release.
Bump version in pyproject.toml and src/gitlab_mcp_lite/__init__.py (a test keeps them equal), add a changelog
entry, merge to main. One-time setup: a GitHub environment named pypi, and either the repository secret
PYPI_API_TOKEN or a trusted publisher on PyPI for this repository (workflow ci.yml, environment pypi).
Status
Alpha. Covers one project per call and the most common read/write operations; it is not a full GitLab client. It originated in the Embersail project's GitLab tooling. Plans for the next editions are in TODO.md.
License
MIT
Available Tools
9 toolsgitlab_issue_commentB
Post a comment (note) on an issue. Append-only.
Inputs: iid (required), body (required), project.
gitlab_issue_getARead-only
Fetch one issue by iid: title, description, state, labels, assignees, milestone, dates.
Inputs: iid (required), project.
gitlab_issues_listARead-only
List issues. state: opened (default), closed or all. labels: all must match. Paged with per_page and page.
Inputs: page, state, labels, project, +1 more.
gitlab_job_playA
Play a manual job. dry_run (default true) only reads the job's status.
Inputs: job_id (required), dry_run, project.
gitlab_mr_createB
Create a merge request. dry_run (default true) only checks that both branches exist.
Inputs: title (required), source_branch (required), target_branch (required), labels, +3 more.
gitlab_mr_listARead-only
List merge requests (state opened by default; opened, closed, merged or all). Paged with per_page and page.
Inputs: page, state, project, per_page.
gitlab_pipeline_createA
Create a pipeline for a branch or tag. dry_run (default true) only checks that the ref exists.
Inputs: ref (required), dry_run, project.
gitlab_pipeline_getARead-only
Fetch one pipeline by id (status, ref, sha, web_url).
Inputs: pipeline_id (required), project.
gitlab_pipeline_jobsBRead-only
List the jobs of a pipeline (id, name, status, stage, web_url).
Inputs: pipeline_id (required), page, project, per_page.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct GitLab resource and action: pipelines, jobs, issues, or merge requests. There is no meaningful overlap between listing jobs, playing a job, creating a pipeline, or creating an MR.
All tools use a clear gitlab_ prefix and snake_case, mostly following resource_action ordering. Minor inconsistencies exist, such as gitlab_pipeline_jobs lacking a list verb and singular/plural mixing (issue_get vs issues_list).
Nine tools is well within the appropriate range for a focused GitLab lite server. Each tool has a clear role and the set does not feel bloated.
The surface covers useful subsets of pipelines, jobs, issues, and merge requests, but has notable gaps: no issue create/update, no MR get/merge, and no pipeline cancel/retry. The 'lite' scope explains some omissions, but agents may still hit dead ends for common workflows.
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.
Operate GitHub from your AI assistant: repos, PRs, issues, Actions. Previews and read-only mode.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables project management and repository operations on GitLab through the GitLab API, including file operations, branch management, issue creation, merge requests, and repository forking with support for both GitLab.com and self-hosted instances.Apache 2.0
- AlicenseBqualityCmaintenanceProvides full control over GitLab epics, issues, merge requests, pipelines, and more via a conversational interface, with dry-run safety.10021 npm2MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying GitLab projects, pipelines, and jobs, and triggering manual deployment jobs after user confirmation, with secure token handling and scope restrictions.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to query and manage GitLab projects, issues, merge requests, and file contents via the GitLab REST API v4.269 npmMIT