Efficient GitLab MCP

Token-Efficient GitLab Server Management — An enhanced fork of zereight/gitlab-mcp with progressive disclosure pattern for dramatic token savings.

What's Different From Upstream?

This fork builds on the original GitLab MCP with substantial engineering improvements:

Area	Upstream	This Fork
Runtime	Node.js + npm	Bun (faster builds, native TypeScript)
Tool Exposure	100+ tools directly	5 meta-tools (progressive disclosure)
Testing	Basic	Comprehensive test suite
Linting	ESLint + Prettier	Strict Biome rules (noExplicitAny, noNonNullAssertion, cognitive complexity)
CI/CD	Basic	GitHub Actions (lint, build, test, semantic-release)
Pre-commit	None	prek hooks (typos, formatting, build verification)

Key Improvements

• Progressive Disclosure — 5 meta-tools instead of 100+ individual tools (~90% token reduction)
• MCP Protocol Logging — Structured logs sent to LLM clients for agent observability
• HTTP Transport Security — DNS rebinding protection, configurable allowed hosts/origins
• Comprehensive Test Suite — 120+ tests covering registry, config, logger, MCP integration, and meta-tools
• Strict Code Quality — Zero any types, no non-null assertions, enforced cognitive complexity limits
• Modern Tooling — Bun for fast builds, Biome for linting, prek for pre-commit hooks
• Automated Releases — Semantic versioning with conventional commits

---

How It Works

Instead of exposing 100+ individual tools, this server exposes 5 meta-tools:

Meta-Tool	Purpose
list_categories	Discover available tool categories
list_tools	List tools in a specific category
search_tools	Search for tools by keyword
get_tool_schema	Get full parameter schema for a tool
execute_tool	Execute any GitLab tool by name

Token Savings

Approach	Tools Exposed	Approximate Token Cost
Traditional	100+ tools	~20,000+ tokens
Progressive Disclosure	5 meta-tools	~1,500 tokens

~90% reduction in tool definition tokens!

Example Workflow

1. LLM calls list_categories() → sees "merge-requests" category
2. LLM calls list_tools("merge-requests") → sees "create_merge_request", "merge_merge_request", etc.
3. LLM calls get_tool_schema("create_merge_request") → sees required params
4. LLM calls execute_tool("create_merge_request", {projectId: "123", title: "Fix bug", sourceBranch: "fix", targetBranch: "main"})

---

Available Operations

All GitLab operations organized by category:

Category	Description
repositories	Search, create, fork repos. Get files, push files, manage branches
merge-requests	Create, update, merge MRs. Discussions, threads, diffs
issues	Create, update, delete issues. Links, discussions
pipelines	List, create, retry, cancel pipelines. Job output
projects	Project details, members, labels
commits	List commits, get diffs
namespaces	List, get, verify namespaces
search	Global, project, and group search across code, issues, MRs, commits
milestones	Create, edit, delete milestones
wiki	Wiki page management
releases	Release management
users	User details
notes	Comments on issues and MRs
events	User and project activity
groups	Group projects and iterations

---

Quick Start

Prerequisites

• Node.js 18+ (for npx) or Bun 1.0+ (for bunx)
• A GitLab personal access token with the following scopes:
  • api — Full API access (required for most operations)
  • read_api — Read-only API access (if you only need read operations)
  • read_repository — Read repository files
  • write_repository — Push to repositories

MCP Client Configuration

Add this to your MCP client configuration (e.g., ~/.config/claude/claude_desktop_config.json for Claude Desktop, or your IDE's MCP settings):

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["efficient-gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

Or with Bun:

{
  "mcpServers": {
    "gitlab": {
      "command": "bunx",
      "args": ["efficient-gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-xxxxxxxxxxxxxxxxxxxx",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

For self-hosted GitLab, update GITLAB_API_URL to your instance URL.

Connect via CLI

# stdio transport (default)
claude mcp add gitlab-agent -- npx efficient-gitlab-mcp-server

# HTTP transport (requires running from source)
STREAMABLE_HTTP=true npx efficient-gitlab-mcp-server
claude mcp add --transport http gitlab-agent http://localhost:3002/mcp

Install from Source (Development)

git clone https://github.com/detailobsessed/efficient-gitlab-mcp.git
cd efficient-gitlab-mcp
bun install
bun run build
bun start

---

Features

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.

HTTP Transport Security

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 start

---

Development

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Lint and format
bun run check

# Build
bun run build

---

Configuration

Core Settings

Variable	Required	Default	Description
GITLAB_PERSONAL_ACCESS_TOKEN	Yes*	-	GitLab personal access token
GITLAB_API_URL	No	https://gitlab.com	GitLab instance URL
GITLAB_PROJECT_ID	No	-	Default project ID
GITLAB_ALLOWED_PROJECT_IDS	No	-	Comma-separated allowed project IDs
GITLAB_READ_ONLY_MODE	No	false	Disable write operations
GITLAB_IS_OLD	No	false	For older GitLab instances

Transport Settings

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

Feature Flags

Variable	Required	Default	Description
USE_GITLAB_WIKI	No	false	Enable wiki tools
USE_MILESTONE	No	false	Enable milestone tools
USE_PIPELINE	No	false	Enable pipeline tools

Logging & Security

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

Remote Authorization (Multi-tenant)

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

*Or use OAuth authentication - see OAuth Setup Guide

---

Security

• Never commit tokens — Use .env files (gitignored)
• Rotate tokens — Regenerate periodically
• Least privilege — Only grant necessary API scopes
• Audit logs — Monitor API access

---

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.

---

Efficient GitLab MCP
AI-Powered GitLab Management with Token Efficiency
_{Built with Bun and the Model Context Protocol}