Efficient GitLab MCP

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

Other Improvements

• Read-Only Mode & PAT Safety — Automatic PAT scope detection, explicit read-only mode, and actionable 403 error messages.
• Secret redaction — runners_token is redacted from project responses by default; opt back in with include_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 any types, no non-null assertions, enforced cognitive complexity limits.
• Automated releases — Semantic versioning with conventional commits.

Available Categories

All GitLab operations are organized into 16 categories totaling 167 tools. All categories are registered at startup but dormant — activate the ones you need.

How It Works

A typical agent session uses three phases — discover, activate, work — and optionally cleans up with deactivate once a category is no longer needed.

1. Discover (~1.5K tokens)

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

2. Activate

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.

3. Work

> create_merge_request({
    project_id: "123",
    title: "Fix bug",
    source_branch: "fix",
    target_branch: "main"
  })

{ "id": 7891, "iid": 42, "title": "Fix bug", "state": "opened", ... }

4. Deactivate (optional)

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.

Configuration

Core Settings

*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).

Transport Settings

Logging & Security

Remote Authorization (Multi-tenant)

Features

Read-Only Mode & PAT Safety

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

Secret Redaction

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.

Tool Annotations

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.

MCP Protocol Logging

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.

HTTP Transport Security

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

Troubleshooting

My agent activated a category but can't see the new tools

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.

"403 Forbidden" on a tool I expected to work

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 rejected

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

Self-hosted GitLab not connecting

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.

CI tools don't work in GitLab CI

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 responses

It's redacted by default for safety. To get it back, pass include_secrets: true on the call.

List endpoint returns fewer results than expected

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 logs

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

Development

# 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

Schema-drift CI

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:

• Before merging a PR that touches src/schemas/ — catches schema bugs against a real instance, complementing the fixture-based unit tests.
• After upgrading a self-hosted GitLab — quick sanity check that nothing in the response shape moved.
• Triaging suspicious LLM behavior — if responses look wrong but the tool returned OK, a schema mismatch silently passed through; drift check confirms or rules that out.

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.

Upstream Tracking

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.

Security

• Never commit tokens — Use .env files (gitignored)
• Rotate tokens — Regenerate periodically
• Least privilege — Only grant necessary API scopes
• Audit logs — Monitor API access
• Secret redaction — runners_token is redacted by default; see Secret Redaction

Acknowledgments

This project is a fork of zereight/gitlab-mcp. Thanks to the original author for the comprehensive GitLab API implementation.

Resources

• MCP Protocol: modelcontextprotocol.io
• GitLab API: docs.gitlab.com/ee/api
• Bun: bun.sh

License

MIT License — See LICENSE for details.