Token-efficient GitLab MCP server. A fork of zereight/gitlab-mcp re-architected for agent context budgets: 167 tools delivered through 3 meta-tools, with field projection on every list endpoint, server-side file trimming, and keyset pagination on large directories.
If your agent's first turn against an MCP server costs ~20K tokens of tool definitions before you've asked anything, this fork is for you.
- A GitLab Personal Access Token with
apiscope (orread_apifor read-only). Create one → - Node.js 18+ (for
npx) or Bun 1.0+ (forbunx)
Add this to your MCP client config — Claude Desktop, Cursor, Claude Code, IDE extensions, etc.:
{
"mcpServers": {
"gitlab": {
"command": "npx",
"args": ["efficient-gitlab-mcp-server@latest"],
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com"
}
}
}
}Restart your client. The server is live with 3 meta-tools (list_categories, activate_tools, deactivate_tools). Your agent discovers GitLab tools by activating categories on demand — see How It Works for a worked example.
Prefer
bun? Replace"command": "npx"with"command": "bunx".
Self-hosted GitLab — point at your instance's base URL (the server appends /api/v4 itself):
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.your-company.com"
}Pinned to a single project — agents don't need to repeat project_id; it's used as a default:
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"GITLAB_PROJECT_ID": "12345"
}Restricted to multiple projects — every call must specify a project_id from the allow-list:
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"GITLAB_ALLOWED_PROJECT_IDS": "12345,67890,123"
}Read-only (auto-detected) — use a PAT with only read_api scope; the server detects the limited scope at startup and only exposes the 93 read tools. No extra config needed.
Read-only (forced) — keep your api-scope PAT but force read-only mode at the server level:
"env": {
"GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
"GITLAB_API_URL": "https://gitlab.com",
"GITLAB_READ_ONLY_MODE": "true"
}Claude Code CLI (one-liner add):
claude mcp add -s user gitlab \
-e GITLAB_PERSONAL_ACCESS_TOKEN=glpat-xxxxxxxxxxxxxxxxxxxx \
-e GITLAB_API_URL=https://gitlab.com \
-- npx efficient-gitlab-mcp-server@latestGitLab CI runner — CI_JOB_TOKEN is auto-detected if no PAT is set. Use GITLAB_PROJECT_ID: $CI_PROJECT_ID to scope to the running project. No extra setup.
From source (development):
git clone https://github.com/detailobsessed/efficient-gitlab-mcp.git
cd efficient-gitlab-mcp
bun install
bun run build
bun startHit a snag? See Troubleshooting. Need to tune more env vars? See full Configuration reference.
- Quick Start
- Why this fork?
- Token Efficiency
- What's Different From Upstream?
- Available Categories
- How It Works
- Configuration
- Features
- Troubleshooting
- Development
- Upstream Tracking
- Security
- Acknowledgments
- License
GitLab's API surface is huge, and the upstream MCP server reflects that — every tool is exposed at startup, all the time. For an agent on a context budget, that's wasteful in three places:
- Tool definitions at startup. Hundreds of tool schemas are forced into the prompt before the first user turn.
- List-endpoint responses. GitLab list endpoints return objects with 100+ fields per row by default; relevant signal is usually <10 fields.
- File contents and large directories. Reading a single file can pull in thousands of irrelevant lines; listing a large repository tree returns everything at once.
This fork addresses all three: progressive disclosure for tool definitions, field projection for list responses, and trimming + keyset pagination for content.
Instead of exposing 167 individual tools, the server exposes 3 meta-tools:
| Meta-Tool | Purpose |
|---|---|
list_categories |
Discover available tool categories and their activation status |
activate_tools |
Enable all tools in one or more categories |
deactivate_tools |
Disable a category once you're done — frees the tokens back |
| Approach | Tools Exposed | Approximate Token Cost |
|---|---|---|
| Traditional | 167 tools | ~20,000+ tokens |
| Progressive Disclosure | 3 meta-tools | ~1,500 tokens |
~90% reduction in tool-definition tokens at startup. Tools are registered with the MCP SDK but kept disabled (tool.disable()) until the LLM activates a category — activation triggers a tools/list_changed notification so the client picks them up live.
List endpoints return a curated, allow-listed default set of fields per resource. Callers can opt into the full payload with fields: "all" or pick their own list with fields: ["id", "name"].
Currently applied to:
list_projects,list_group_projectslist_issues,my_issueslist_merge_requestslist_pipelineslist_releaseslist_commits
A spike measurement against list_projects with 5 owned projects went from ~32 KB → ~3 KB by switching to the compact default. Because it's allow-list based, the compact output stays compact when GitLab adds new fields upstream.
get_file_contents accepts trim parameters so agents don't have to pull whole files into context just to read a function:
| Parameter | Purpose |
|---|---|
head: N |
Return only the first N lines |
tail: N |
Return only the last N lines |
range: "start-end" |
Return a specific line range |
max_bytes: N |
Hard byte cap (composes with line-based trims) |
Truncated responses include a note like Showing lines 100-200 of 5234, so a follow-up call can target a different range without re-fetching to count lines first.
get_repository_tree supports keyset pagination (pagination=keyset) and returns an envelope:
{
"items": [...],
"pagination_note": "Next page available — call again with pagination=keyset&page_token=..."
}Large monorepos no longer dump 10K entries into a single response. The server reads the cursor from X-Next-Page-Token (or falls back to X-Next-Page on older GitLab instances) and surfaces it inline.
This fork builds on zereight/gitlab-mcp with a redesigned architecture focused on token efficiency and maintainability. We regularly review upstream commits and selectively port new features and bugfixes — we don't blindly rebase, since the codebases have structurally diverged.
| Area | Upstream | This Fork |
|---|---|---|
| Architecture | Single index.ts (~10K lines) |
Modular src/ with 16 tool modules |
| Tool Discovery | All 140+ tools exposed at once | SDK-native progressive disclosure (3 meta-tools) |
| List Responses | Full GitLab payload (100+ fields/row) | Field projection: compact default + opt-in fields |
| File Contents | Whole-file fetch | Server-side head / tail / range / max_bytes trimming |
| Tree Listing | Offset pagination only | Offset + keyset (pagination=keyset) with cursor envelope |
| Tool Annotations | Partial | Complete: readOnlyHint / destructiveHint / idempotentHint / openWorldHint on every tool |
| Configuration | Flat individual exports | Typed ServerConfig interface with loadConfig() |
| Logging | console.log |
Structured MCP protocol logger for agent observability |
| Runtime | Node.js + npm | Bun (faster builds, native TypeScript) |
| Linting | ESLint + Prettier | Strict Biome rules (noExplicitAny, noNonNullAssertion, cognitive complexity cap) |
| CI/CD | Basic | GitHub Actions (lint, build, test, semantic-release) |
| Pre-commit | None | prek hooks (typos, formatting, build verification) |
| Feature Flags | USE_PIPELINE, USE_MILESTONE, USE_GITLAB_WIKI required |
None — all categories registered, dormant until activated |
- Read-Only Mode & PAT Safety — Automatic PAT scope detection, explicit read-only mode, and actionable 403 error messages.
- Secret redaction —
runners_tokenis redacted from project responses by default; opt back in withinclude_secrets: true. - Robust schema coercion — Booleans, numeric IDs, and stringified arrays are all coerced defensively (LLMs serialize inconsistently).
- HTTP transport security — DNS rebinding protection, configurable allowed hosts/origins.
- Comprehensive test suite — 280+ tests covering registry, config, logger, MCP integration, read-only mode, projection, and meta-tools.
- Strict code quality — Zero
anytypes, no non-null assertions, enforced cognitive complexity limits. - Automated releases — Semantic versioning with conventional commits.
All GitLab operations are organized into 16 categories totaling 167 tools. All categories are registered at startup but dormant — activate the ones you need.
| Category | Tools | Description |
|---|---|---|
repositories |
11 | Search, create, fork repos. Get/push files, manage branches, list tree |
merge-requests |
33 | Create, update, merge MRs. Discussions, threads, diffs |
issues |
14 | Create, update, delete issues. Links, discussions |
pipelines |
19 | List, create, retry, cancel pipelines. Job output |
projects |
10 | Project details, list, members, labels |
commits |
3 | List commits, get commits, get diffs |
namespaces |
3 | List, get, verify namespaces |
users |
8 | User details, search, audit/project events, file uploads, current user (whoami) |
search |
6 | Global, project, and group search across code, issues, MRs, commits |
wiki |
10 | Wiki page management for projects and groups |
milestones |
9 | Create, edit, delete milestones. Burndown events |
releases |
7 | List, create, update, delete releases. Download assets |
webhooks |
3 | List project webhooks and recent events |
work-items |
12 | GraphQL work items: create, update, hierarchy, notes, incidents |
graphql |
1 | Execute arbitrary GraphQL queries |
emoji-reactions |
18 | Add, remove, and list emoji reactions on MRs / issues / work items / notes (REST + GraphQL) |
A typical agent session uses three phases — discover, activate, work — and optionally cleans up with deactivate once a category is no longer needed.
When the MCP client connects, the server only exposes 3 meta-tools. The agent calls list_categories to see what's available:
The agent decides what it needs and activates a category:
> activate_tools({ categories: ["merge-requests"] })
"Activated 33 tools in category 'merge-requests'."The server fires a tools/list_changed notification so the client picks up the 33 new tool definitions live.
Claude Code latency note: tools activated mid-turn become callable starting from the next turn (Claude Code rebuilds its deferred-tool index between turns). Other clients can be eager.
> create_merge_request({
project_id: "123",
title: "Fix bug",
source_branch: "fix",
target_branch: "main"
})
{ "id": 7891, "iid": 42, "title": "Fix bug", "state": "opened", ... }When the agent is done with this category, it can free the tokens back:
> deactivate_tools({ categories: ["merge-requests"] })
"Deactivated 33 tools in category 'merge-requests'."This is especially useful in long agent sessions where context is at a premium — pull only what you need, drop it when you're done, then pull a different category.
| Variable | Required | Default | Description |
|---|---|---|---|
GITLAB_PERSONAL_ACCESS_TOKEN |
Yes* | - | GitLab personal access token (takes priority over CI_JOB_TOKEN) |
CI_JOB_TOKEN |
No | - | GitLab CI job token (auto-detected in CI pipelines) |
GITLAB_API_URL |
No | https://gitlab.com |
GitLab instance URL |
GITLAB_PROJECT_ID |
No | - | Default project ID when tools omit project_id |
GITLAB_ALLOWED_PROJECT_IDS |
No | - | Restrict tools to these projects (comma-separated). With a single project, acts as default. With multiple, project_id is required per call |
GITLAB_READ_ONLY_MODE |
No | false |
Only expose read-only tools. Auto-detected from PAT scopes if not set |
GITLAB_IS_OLD |
No | false |
For older GitLab instances |
*PAT is recommended. CI_JOB_TOKEN is auto-detected in GitLab CI pipelines when no PAT is set. OAuth support is planned (see OAuth Setup Guide).
| Variable | Required | Default | Description |
|---|---|---|---|
STREAMABLE_HTTP |
No | false |
Enable HTTP transport |
SSE |
No | false |
Enable SSE transport |
PORT |
No | 3002 |
HTTP server port |
HOST |
No | 127.0.0.1 |
HTTP server host |
| Variable | Required | Default | Description |
|---|---|---|---|
LOG_LEVEL |
No | info |
debug, info, warn, error |
LOG_FORMAT |
No | pretty |
json, pretty |
HTTP_ALLOWED_HOSTS |
No | localhost,127.0.0.1 |
Allowed Host headers |
HTTP_ALLOWED_ORIGINS |
No | (any) | Allowed Origin headers |
HTTP_ENABLE_DNS_REBINDING_PROTECTION |
No | true |
Enable DNS rebinding attack protection |
| Variable | Required | Default | Description |
|---|---|---|---|
REMOTE_AUTHORIZATION |
No | false |
Enable remote auth |
ENABLE_DYNAMIC_API_URL |
No | false |
Allow dynamic GitLab URLs |
SESSION_TIMEOUT_SECONDS |
No | 3600 |
Session timeout |
MAX_SESSIONS |
No | 1000 |
Maximum concurrent sessions |
MAX_REQUESTS_PER_MINUTE |
No | 60 |
Rate limit per session |
The server provides three layers of protection for users with limited-scope Personal Access Tokens:
1. Explicit read-only mode — Set GITLAB_READ_ONLY_MODE=true to restrict the server to read-only tools. Write tools won't appear in list_categories counts and can't be activated. This is driven by the readOnlyHint annotation on every tool.
2. Automatic PAT scope detection — On startup, the server calls GitLab's GET /personal_access_tokens/self to inspect your token's scopes. If the token lacks the api scope (e.g., only has read_api), read-only mode is automatically enabled. No configuration needed — it just works.
3. Actionable 403 error messages — If a tool call hits a 403 Forbidden error, the error message includes specific guidance about which PAT scopes are needed, so the LLM can inform the user rather than retrying blindly.
# Explicit read-only mode
GITLAB_READ_ONLY_MODE=true
# Or just use a read_api token — auto-detected!
GITLAB_PERSONAL_ACCESS_TOKEN=glpat-your-read-only-token
GitLab project responses include a runners_token field by default — anyone with that token can register CI runners against the project. The server redacts runners_token by default on get_project and list_projects responses. To opt back in (e.g. when an agent specifically needs to manage runner registration), pass include_secrets: true.
Every tool declares a complete set of MCP tool annotations so MCP-aware clients can offer per-action confirmation, distinguish destructive operations from idempotent updates, and filter by side-effect profile:
| Tool kind | readOnlyHint |
destructiveHint |
idempotentHint |
openWorldHint |
|---|---|---|---|---|
| Read-only (list/get) | true |
(omit) | (omit) | true |
| Create | false |
false |
false |
true |
| Update | false |
true |
true |
true |
| Delete | false |
true |
true |
true |
openWorldHint is always true because every tool talks to GitLab's API. The annotation matrix is enforced by an invariants test.
The server supports MCP protocol logging for agent observability. When connected, LLM clients can receive structured log messages showing what the server is doing:
- Tool execution logs
- GitLab API call details
- Error information with context
This helps agents understand server behavior and debug issues — instead of opaque console.log output that only the developer sees.
When using HTTP transport (STREAMABLE_HTTP=true), the server includes security features:
| Environment Variable | Default | Description |
|---|---|---|
HTTP_ALLOWED_HOSTS |
localhost,127.0.0.1 |
Comma-separated list of allowed Host headers |
HTTP_ALLOWED_ORIGINS |
(any) | Comma-separated list of allowed Origin headers |
HTTP_ENABLE_DNS_REBINDING_PROTECTION |
true |
Enable DNS rebinding attack protection |
Example for production:
HTTP_ALLOWED_HOSTS=api.example.com,localhost \
HTTP_ALLOWED_ORIGINS=https://app.example.com \
STREAMABLE_HTTP=true \
bun startYour MCP client needs to support the tools/list_changed notification for runtime activations to be picked up. Most modern clients do.
In Claude Code specifically, activated tools become callable starting from the next turn — the client rebuilds its deferred-tool index between turns, not synchronously inside one. So calling activate_tools({ categories: ["issues"] }) and then list_issues() in the same turn won't work; the next turn will. Other clients (Claude Desktop, Cursor) tend to be eager.
The server returns actionable 403s — the error message tells you which PAT scopes are missing. Common cause: your PAT only has read_api scope (read-only) but the tool you called requires api. Either regenerate a PAT with api scope, or stay in read-only mode and use the read tools.
If GITLAB_ALLOWED_PROJECT_IDS is set with multiple comma-separated IDs, every tool call needs an explicit project_id matching one of them — there's no default. With a single ID, that ID is used as the default if no project_id is passed. Empty/unset means no restriction (any project ID is allowed).
GITLAB_API_URL should be your instance's base URL (https://gitlab.your-company.com), not the API path. The server appends /api/v4 itself. If you use the base path with /api/v4 already in it, calls will hit /api/v4/api/v4/... and 404.
If GITLAB_PERSONAL_ACCESS_TOKEN isn't set, the server falls back to CI_JOB_TOKEN automatically (auto-detected from the GitLab CI environment). Set GITLAB_PROJECT_ID: $CI_PROJECT_ID in your .gitlab-ci.yml so the running pipeline's project is used as the default scope.
It's redacted by default for safety. To get it back, pass include_secrets: true on the call.
For list_issues, list_merge_requests, etc.: GitLab's global endpoints (when no project_id is supplied) historically defaulted to scope: created_by_me. To see everything, pass scope: "all" explicitly. If you supply project_id, the call routes to the project-scoped endpoint and this default doesn't apply.
# Install dependencies
bun install
# Run tests (280+ tests, <1s)
bun test
# Run tests with coverage
bun test --coverage
# Lint and format
bun run check
# Build
bun run buildWe maintain main as a read-only mirror of upstream. New features and bugfixes from upstream are reviewed and ported into our architecture as needed — we don't blindly rebase, since the codebases have structurally diverged. If you're looking for a specific upstream feature, check our releases or open an issue.
- Never commit tokens — Use
.envfiles (gitignored) - Rotate tokens — Regenerate periodically
- Least privilege — Only grant necessary API scopes
- Audit logs — Monitor API access
- Secret redaction —
runners_tokenis redacted by default; see Secret Redaction
This project is a fork of zereight/gitlab-mcp. Thanks to the original author for the comprehensive GitLab API implementation.
- MCP Protocol: modelcontextprotocol.io
- GitLab API: docs.gitlab.com/ee/api
- Bun: bun.sh
MIT License — See LICENSE for details.
Efficient GitLab MCP
AI-Powered GitLab Management with Token Efficiency
Built with Bun and the Model Context Protocol
> list_categories() { "categories": [ { "name": "repositories", "tools": 11, "active": false, "description": "Search, create, fork repos. Get/push files, manage branches, list tree" }, { "name": "merge-requests", "tools": 33, "active": false, "description": "Create, update, merge MRs. Discussions, threads, diffs" }, { "name": "issues", "tools": 14, "active": false, "description": "Create, update, delete issues. Links, discussions" }, // ... 13 more, 167 tools total ] }