Power your agent
คำสั่งของผู้เผยแพร่เอง ไม่ใช่เอนด์พอยต์ของ PlugMCP
Host a copy with our keys and logs.
npx -y [email protected]Claude Code ไม่มีลิงก์ติดตั้งสำหรับคำสั่งแบบโลคัล ให้คัดลอกคำสั่งด้านล่างแล้วรันในเทอร์มินัล
GITLAB_PERSONAL_ACCESS_TOKEN=<secret> GITLAB_API_URL=<value> claude mcp add io.github.detailobsessed-efficient-gitlab -- npx -y efficient-gitlab-mcp-server@2.33.0รันในเทอร์มินัล
{ "mcpServers": { "io.github.detailobsessed-efficient-gitlab": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "<secret>", "GITLAB_API_URL": "<value>" } } }}claude_desktop_config.json
URL แบบรีโมตหรือคำสั่งบนเครื่องของคุณ? การติดตั้งสองแบบต่างกันอย่างไร
รันบน PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
เปิดจากผู้เผยแพร่
[!CAUTION] This repository is archived (2026-05-22).
Upstream
zereight/gitlab-mcpv2.1+ has independently implemented progressive disclosure and schema slimming (commit ). The differentiators that justified this fork no longer apply — please use upstream instead.
Token-efficient GitLab MCP: 167 tools via 3 meta-tools, field projection, keyset pagination
44983ecToken-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.
api scope (or read_api for read-only). Create one →npx) or Bun 1.0+ (for bunx)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@latest
GitLab 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 start
Hit a snag? See Troubleshooting. Need to tune more env vars? See full Configuration reference.
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:
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:
~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 — and a growing set of singular get_* 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_projects, get_projectlist_issues, my_issues, get_issuelist_merge_requests, get_merge_requestlist_pipelines, get_pipelinelist_releaseslist_commits, get_commitget_current_user, get_user, get_users, search_usersA 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.
Example — fetch a merge request with the compact default vs. the full GitLab payload:
// Default: ~17 fields (iid, title, state, draft, labels, branches, author, …)
{ "name": "get_merge_request", "arguments": { "merge_request_iid": 42 } }
// Opt out: the raw GitLab response
{ "name": "get_merge_request", "arguments": { "merge_request_iid": 42, "fields": "all" } }
// Custom pick
{ "name": "get_merge_request", "arguments": { "merge_request_iid": 42, "fields": ["iid", "title", "state"] } }
The slim defaults are derived from the same Zod response schemas that validate GitLab API responses (see src/schemas/), so they stay in sync with the type-level shape and there's a single source of truth per resource.
get_file_contents accepts trim parameters so agents don't have to pull whole files into context just to read a function:
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.
runners_token is redacted from project responses by default; opt back in with include_secrets: true.any types, no non-null assertions, enforced cognitive complexity limits.All GitLab operations are organized into 16 categories totaling 167 tools. All categories are registered at startup but dormant — activate the ones you need.
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:
> 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
]
}
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.
*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).
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:
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:
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:
Example for production:
HTTP_ALLOWED_HOSTS=api.example.com,localhost \
HTTP_ALLOWED_ORIGINS=https://app.example.com \
STREAMABLE_HTTP=true \
bun start
Your 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.
project_id keeps getting rejectedIf 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.
runners_token is missing from project responsesIt'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.
GitLab response failed schema validation in MCP server logsGitLab responses on the server's schematized read endpoints (users, projects, merge requests, commits, issues, pipelines, repository tree) run through a Zod schema. On a mismatch the server logs WARN GitLab response failed schema validation; passing through unchanged with the field path and Zod error code, then passes the response on to your LLM unchanged — so the call still succeeds, but you've got a signal that GitLab returned a shape we don't know about. Causes are usually GitLab API drift (new field, type change, removal) or a self-hosted EE instance returning EE-only fields. If you see one of these warnings, open an issue with the path, code, and which tool triggered it — that's our cue to update the schema.
# 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 build
The runtime path through parseGitLabResponse is intentionally lenient (.safeParse() + log warning + pass through) so an unexpected GitLab field never blocks an MCP tool call. The drift gate is the strict counterpart: a Bun script that calls every response-schema-bearing GitLab REST endpoint and .parse()s each response against its declared Zod schema, failing on any mismatch.
Run it locally:
export GITLAB_API_URL=https://gitlab.com
export GITLAB_PERSONAL_ACCESS_TOKEN=glpat-... # read_api scope only
export GITLAB_PROJECT_ID=12345 # must have ≥1 MR/commit/issue/pipeline
bun run drift
When to run it manually:
src/schemas/ — catches schema bugs against a real instance, complementing the fixture-based unit tests.The same script runs in CI via .github/workflows/schema-drift.yml — schedule Mondays 06:00 UTC and workflow_dispatch on demand. The same three env vars are wired as repo secrets.
We 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.
.env files (gitignored)runners_token is redacted by default; see Secret RedactionThis project is a fork of zereight/gitlab-mcp. Thanks to the original author for the comprehensive GitLab API implementation.
MIT License — See LICENSE for details.
Token-efficient GitLab MCP: 167 tools via 3 meta-tools, field projection, keyset pagination
{ "mcpServers": { "io.github.detailobsessed-efficient-gitlab": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "GITLAB_PERSONAL_ACCESS_TOKEN": "<secret>", "GITLAB_API_URL": "<value>" } } }}เครื่องมือ
ยังไม่มีรายการเครื่องมือ เซิร์ฟเวอร์แบบรีโมตจะได้รายการหลังการตรวจสอบสถานะครั้งแรก
FAQ
คัดลอกคอนฟิก stdio สำหรับ Cursor, Claude Desktop, Claude Code หรือ VS Code ได้ในหน้านี้ คอนฟิกนี้ใช้การติดตั้งของผู้เผยแพร่ ไม่ใช่พร็อกซีของ PlugMCP
ผู้เผยแพร่ระบุตัวแปรสภาพแวดล้อมเหล่านี้: GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_API_URL
Efficient Gitlab ทำงานแบบโลคัลผ่าน stdio
ตรวจสอบล่าสุดเมื่อ 2026-11-09 Token-efficient GitLab MCP: 167 tools via 3 meta-tools, field projection, keyset pagination