npm package: @redserenity/mcp-gitlab-server
Description: Token-efficient GitLab MCP server with modular features
Author: Tyler Andersen
Latest version: 1.1.0

# 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

```bash
# 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

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

### Method 3: Using Docker

```bash
# 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`:

```bash
# 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

```bash
# 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:
```bash
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`)

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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**

```json
{
  "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`)

```json
{
  "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`)

```json
{
  "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:

```bash
yarn start --projects --issues --labels
```

### StreamableHTTP Transport

Best for remote clients and web integrations:

```bash
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

```bash
# 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:

```json
{
  "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

```json
{
  "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

```json
{
  "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

```json
{
  "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:

```json
{
  "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