GitLab MCP Server

A token-efficient GitLab MCP server with modular features, supporting both STDIO and StreamableHTTP transports.

Features

• Token-efficient design - Consolidated tools with command parameters to minimize token usage
• Dual transport support - Both STDIO and StreamableHTTP via CLI arguments or environment variables
• Modular features - Enable/disable tool groups via CLI flags
• Innovative IssueTasks tool - Efficiently manage GitLab issue markdown checklists without regenerating entire descriptions
• Caching support - Optional intelligent caching with configurable TTL
• Syntax resource - Dynamic parameter documentation for token-efficient usage

Installation

Method 1: From Source

# Clone the repository
git clone https://gitlab.com/RedSerenity/McpServers/GitLab.git
cd GitLab

# Install dependencies
yarn install

# Build the project
yarn build

Method 2: Using NPX

# Run directly with npx (no installation required)
npx @redserenity/gitlab-mcp-server --projects --issues --wiki --labels

Method 3: Using Docker

# Pull and run the Docker image
docker run -e GITLAB_TOKEN=your_token_here \
  -e GITLAB_URL=https://gitlab.com \
  redserenity/gitlab-mcp-server:latest \
  --projects --issues --wiki --labels

Configuration

Environment Variables

Create a .env file based on .env.example:

# GitLab Configuration
GITLAB_TOKEN=your_gitlab_token_here
GITLAB_URL=https://gitlab.com

# MCP Server Configuration
MCP_TRANSPORT=stdio
MCP_PORT=3000
LOG_LEVEL=info

# Feature Configuration (optional)
ENABLE_PROJECTS=true
ENABLE_ISSUES=true
ENABLE_WIKI=true
ENABLE_LABELS=true

# Resource Configuration (optional)
ENABLE_RESOURCES=true
DISABLE_PROJECT_RESOURCES=false
DISABLE_ISSUE_RESOURCES=false
DISABLE_WIKI_RESOURCES=false
DISABLE_LABELS_RESOURCES=false

# Cache Configuration (optional)
ENABLE_CACHE=true
CACHE_TTL_LIST=300
CACHE_TTL_GET=60
CACHE_MAX_SIZE=1000

GitLab Token

You need a GitLab personal access token with appropriate scopes:

• api - Full API access
• read_user - Read user profile
• read_repository - Read repository content

Usage

Basic Usage

# STDIO transport (default) with all features
yarn start --projects --issues --wiki --labels

# HTTP transport on port 3000
yarn start --transport=http --port=3000 --projects --issues --wiki --labels

# Enable only specific features
yarn start --projects --issues --labels

# With caching enabled
yarn start --cache --projects --issues --labels

Command Line Options

• --transport <type> - Transport type: stdio or http (default: stdio)
• --port <number> - Port for HTTP transport (default: 3000)
• --projects - Enable Projects and Groups tools
• --issues - Enable Issues and IssueTasks tools
• --wiki - Enable Wiki tool
• --labels - Enable Labels tool
• --cache - Enable intelligent caching (default: true)
• --cache-ttl-list <seconds> - List cache TTL in seconds (default: 300)
• --cache-ttl-get <seconds> - Get cache TTL in seconds (default: 60)
• --cache-max-size <entries> - Maximum cache entries (default: 1000)
• --log-level <level> - Log level: debug, info, warn, error (default: info)

Environment Variable Override

You can also use environment variables:

MCP_TRANSPORT=http MCP_PORT=8080 yarn start --projects --issues

Tool Architecture

Each tool uses a consolidated command-based architecture to minimize token usage:

Projects Tool (enabled by --projects)

{
  "command": "list|get|create|update",
  "projectId": "optional-project-id",
  "data": { "optional-data-object" },
  "bypassCache": "optional-boolean"
}

Note: Check the gitlab://syntax resource for detailed parameter documentation.

Commands:

• list - List projects
• get - Get specific project (requires projectId)
• create - Create new project (requires data.name)
• update - Update existing project (requires projectId and data)

Groups Tool (enabled by --projects)

{
  "command": "list|get|create",
  "groupId": "optional-group-id",
  "data": { "optional-data-object" }
}

Commands:

• list - List groups
• get - Get specific group (requires groupId)
• create - Create new group (requires data.name and data.path)

Issues Tool (enabled by --issues)

{
  "command": "list|get|create|update|close|reopen",
  "projectId": "optional-project-id",
  "issueId": "optional-issue-id",
  "data": { "optional-data-object" }
}

Commands:

• list - List issues (optionally filtered by projectId)
• get - Get specific issue (requires projectId and issueId)
• create - Create new issue (requires projectId and data.title)
• update - Update existing issue (requires projectId, issueId, and data)
• close - Close issue (requires projectId and issueId)
• reopen - Reopen issue (requires projectId and issueId)

IssueTasks Tool (enabled by --issues) - INNOVATION

{
  "command": "list|completed|not-completed|update|delete",
  "issueId": "required-issue-id",
  "projectId": "optional-project-id",
  "task": "task-text-or-identifier",
  "data": { "optional-data-object" }
}

This innovative tool efficiently manages GitLab issue markdown checklists without regenerating entire issue descriptions:

Commands:

• list - List all tasks in an issue
• completed - Mark a task as completed (requires task)
• not-completed - Mark a task as not completed (requires task)
• update - Update task text (requires task and data.newText)
• delete - Delete a task (requires task)

Benefits:

• Avoids fetching and regenerating entire issue content
• More token-efficient than traditional approaches
• Precise task management with partial text matching
• Maintains issue formatting and other content

Wiki Tool (enabled by --wiki)

{
  "command": "list|get|create|update|delete",
  "projectId": "optional-project-id",
  "slug": "optional-page-slug",
  "data": { "optional-data-object" }
}

Commands:

• list - List wiki pages (requires projectId)
• get - Get specific wiki page (requires projectId and slug)
• create - Create new wiki page (requires projectId, data.title, and data.content)
• update - Update existing wiki page (requires projectId, slug, and data)
• delete - Delete wiki page (requires projectId and slug)

Labels Tool (enabled by --labels)

{
  "command": "list|get|create|update|delete|promote",
  "scope": "project|group",
  "projectId": "optional-project-id",
  "groupId": "optional-group-id",
  "labelId": "optional-label-id",
  "data": { "optional-data-object" }
}

Commands:

• list - List labels (requires projectId for project scope or groupId for group scope)
• get - Get specific label (requires labelId and appropriate scope ID)
• create - Create new label (requires data.name, data.color, and appropriate scope ID)
• update - Update existing label (requires labelId, appropriate scope ID, and data)
• delete - Delete label (requires labelId and appropriate scope ID)
• promote - Promote project label to group label (requires labelId and both projectId and groupId)

Scopes:

• project - Manage labels at project level (default)
• group - Manage labels at group level

Transport Modes

STDIO Transport (Default)

Best for command-line tools and direct integrations:

yarn start --projects --issues --labels

StreamableHTTP Transport

Best for remote clients and web integrations:

yarn start --transport=http --port=3000 --projects --issues --wiki --labels

Access via:

• MCP endpoint: http://localhost:3000/mcp
• Health check: http://localhost:3000/health

Token Efficiency Features

This server is designed to minimize token usage:

1. Consolidated Tools - Single tool per domain instead of multiple tools
2. Command Parameters - All operations via command parameter
3. Selective Features - Only load requested tool groups
4. Efficient IssueTasks - Avoid regenerating entire issue content
5. Minimal Schemas - Concise tool descriptions and validation
6. Syntax Resource - Dynamic parameter documentation at gitlab://syntax
7. Intelligent Caching - Optional caching with configurable TTL to reduce API calls

Development

# Development with auto-rebuild
yarn dev

# Type checking
yarn typecheck

# Clean build artifacts
yarn clean

Error Handling

The server includes comprehensive error handling:

• GitLab API errors are properly mapped and returned
• Rate limiting with automatic retry
• Schema validation for all inputs
• Graceful transport disconnection

MCP Server Configuration Examples

STDIO Configuration

Add to your MCP client's mcpServers configuration:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": [
        "/path/to/GitLab/dist/index.js",
        "--projects",
        "--issues",
        "--wiki"
      ],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

HTTP Configuration

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": [
        "/path/to/GitLab/dist/index.js",
        "--transport=http",
        "--port=3000",
        "--projects",
        "--issues",
        "--wiki"
      ],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

NPX Configuration

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": [
        "@redserenity/gitlab-mcp-server",
        "--projects",
        "--issues",
        "--wiki"
      ],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

Docker Configuration

{
  "mcpServers": {
    "gitlab": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "GITLAB_TOKEN=your_gitlab_token_here",
        "-e", "GITLAB_URL=https://gitlab.com",
        "redserenity/gitlab-mcp-server:latest",
        "--projects",
        "--issues",
        "--wiki"
      ]
    }
  }
}

Configuration with Caching

For better performance with caching enabled:

{
  "mcpServers": {
    "gitlab": {
      "command": "node",
      "args": [
        "/path/to/GitLab/dist/index.js",
        "--projects",
        "--issues",
        "--wiki",
        "--cache",
        "--cache-ttl-list=600",
        "--cache-ttl-get=120"
      ],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token_here",
        "GITLAB_URL": "https://gitlab.com",
        "LOG_LEVEL": "info"
      }
    }
  }
}

License

MIT