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.