Efficient GitLab

Efficient GitLab MCP

[!CAUTION]

This repository is archived (2026-05-22).

Upstream zereight/gitlab-mcp v2.1+ has independently implemented progressive disclosure and schema slimming (commit 44983ec). The differentiators that justified this fork no longer apply — please use upstream instead.

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.

---

Quick Start

Prerequisites

• A GitLab Personal Access Token with api scope (or read_api for read-only). Create one →
• Node.js 18+ (for npx) or Bun 1.0+ (for bunx)

MCP client config (recommended for most users)

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".

Variants

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" }

Other entry points

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.

---

Table of Contents

• Quick Start
• Why this fork?
• Token Efficiency
• Progressive Disclosure
• Field Projection
• Server-Side File Trimming
• Keyset Pagination
• What's Different From Upstream?
• Available Categories
• How It Works
• Configuration
• Features
• Read-Only Mode & PAT Safety
• Secret Redaction
• Tool Annotations
• MCP Protocol Logging
• HTTP Transport Security
• Troubleshooting
• Development
• Upstream Tracking
• Security
• Acknowledgments
• License

---

Why this fork?

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:

1. Tool definitions at startup. Hundreds of tool schemas are forced into the prompt before the first user turn.
2. List-endpoint responses. GitLab list endpoints return objects with 100+ fields per row by default; relevant signal is usually <10 fields.
3. 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.

---

Token Efficiency

Progressive Disclosure

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.

Field Projection

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_project
• list_issues, my_issues, get_issue
• list_merge_requests, get_merge_request
• list_pipelines, get_pipeline
• list_releases
• list_commits, get_commit
• get_current_user, get_user, get_users, search_users

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.

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.

Server-Side File Trimming

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.

Keyset Pagination

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.

---

What's Different From Upstream?

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.

Architecture at a Glance

| Logging | console.log | Structu