GitLab

★ 6

from ZephyrDeng

A GitLab integration server providing access to GitLab's RESTful API tools, built on the fastmcp framework.

🔥🔥🔥✓ VerifiedFreeAdvanced setup

mcp-gitlab MCP Server (English)

A GitLab integration server built on the fastmcp framework, providing various GitLab RESTful API tools. Supports integration with Claude, Smithery, and other platforms.

Features

GitlabSearchUserProjectsTool: Search users and their active projects by username
GitlabGetUserTasksTool: Get current user's pending tasks
GitlabSearchProjectDetailsTool: Search projects and details
GitlabCreateMRCommentTool: Add comments to merge requests
GitlabAcceptMRTool: Accept and merge merge requests
GitlabUpdateMRTool: Update merge request assignee, reviewers, title, description, and labels
GitlabCreateMRTool: Create a new merge request with assignee and reviewers
GitlabRawApiTool: Call any GitLab API with custom parameters

Environment Variables

Copy & paste — that's it

# Required for all modes (optional for httpStream mode - can be provided via HTTP headers)
GITLAB_API_URL=https://your-gitlab-instance.com

# Required for stdio mode, optional for httpStream mode
# (can be provided via HTTP headers in httpStream mode)
GITLAB_TOKEN=your_access_token

# Optional: Provide a mapping from usernames to user IDs (JSON string)
# This can reduce API calls, especially when referencing the same users frequently
# Example: '{"username1": 123, "username2": 456}'
GITLAB_USER_MAPPING={"username1": 123, "username2": 456}

# Optional: Provide a mapping from project names to project IDs (JSON string)
# Project IDs can be numbers or strings (e.g., 'group/project')
# This can reduce API calls and ensure the correct project is used
# Example: '{"project-name-a": 1001, "group/project-b": "group/project-b"}'
GITLAB_PROJECT_MAPPING={"project-name-a": 1001, "group/project-b": "group/project-b"}

# MCP Transport Configuration (Optional)
# Transport type: stdio (default) or httpStream  
MCP_TRANSPORT_TYPE=stdio

# HTTP Stream Configuration (Only used when MCP_TRANSPORT_TYPE=httpStream)
# Server binding address (default: 0.0.0.0 for httpStream, localhost for stdio)
# For Docker deployments, use 0.0.0.0 to allow external access
MCP_HOST=0.0.0.0

# Server port (default: 3000)
MCP_PORT=3000

# API endpoint path (default: /mcp)
MCP_ENDPOINT=/mcp

Transport Modes

This server supports two transport modes:

1. Stdio Transport (Default)

Best for local development and direct integration with MCP clients
Uses stdin/stdout for communication
No network configuration needed

2. HTTP Stream Transport

Enables server deployment for remote access
Uses HTTP POST requests with streaming responses
Allows multiple clients to connect to the same server instance
Ideal for production deployments
Supports dynamic token authentication via HTTP headers

When using HTTP Stream mode, clients can connect to:

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json

Authentication Methods

HTTP Stream mode supports multiple ways to provide GitLab tokens and instance URLs:

Token Authentication:

1. Bearer Token (Recommended):

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
Authorization: Bearer your-gitlab-access-token

2. Private Token Header:

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
PRIVATE-TOKEN: your-gitlab-access-token

3. Alternative Private Token Header:

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
private-token: your-gitlab-access-token

4. Custom GitLab Token Header:

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-token: your-gitlab-access-token

GitLab Instance URL Configuration:

1. GitLab URL Header (Recommended):

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-url: https://gitlab.company.com

2. Alternative GitLab URL Headers:

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-url: https://gitlab.company.com

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-api-url: https://gitlab.company.com

5. Fallback to Environment Variables: If no token or URL is provided in headers, the server will fall back to the GITLAB_TOKEN and GITLAB_API_URL environment variables.

Complete Example:

Copy & paste — that's it

POST http://localhost:3000/mcp
Content-Type: application/json
Authorization: Bearer your-gitlab-access-token
x-gitlab-url: https://gitlab.company.com

Project Structure

Copy & paste — that's it

src/
├── server/
│   └── GitlabMCPServer.ts          # MCP server entry point
├── tools/
│   ├── GitlabAcceptMRTool.ts
│   ├── GitlabCreateMRCommentTool.ts
│   ├── GitlabGetUserTasksTool.ts
│   ├── GitlabRawApiTool.ts
│   ├── GitlabSearchProjectDetailsTool.ts
│   ├── GitlabSearchUserProjectsTool.ts
│   └── gitlab/
│       ├── FieldFilterUtils.ts
│       ├── GitlabApiClient.ts
│       └── GitlabApiTypes.ts
├── utils/
│   ├── is.ts
│   └── sensitive.ts
smithery.json                      # Smithery config
USAGE.md                          # Usage examples
package.json
tsconfig.json

Integration

Claude Desktop Client

Stdio Mode (Default)

Add to your config:

Copy & paste — that's it

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": ["-y", "@zephyr-mcp/gitlab"]
    }
  }
}

HTTP Stream Mode (Server Deployment)

Server Setup: First start the server (note that both GITLAB_TOKEN and GITLAB_API_URL are optional when using HTTP headers):

Copy & paste — that's it

# On your server - no token or URL required in env vars
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 MCP_HOST=0.0.0.0 npx @zephyr-mcp/gitlab

# Or with Docker
docker run -d \
  -p 3000:3000 \
  -e MCP_TRANSPORT_TYPE=httpStream \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3000 \
  gitlab-mcp-server

Client Configuration:

Option 1: With Bearer Token (Recommended)

Copy & paste — that's it

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-cli",
        "http://your-server:3000/mcp",
        "--header", "Authorization: Bearer your-gitlab-access-token"
      ]
    }
  }
}

Option 2: With Private Token Header

Copy & paste — that's it

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-cli",
        "http://your-server:3000/mcp",
        "--header", "PRIVATE-TOKEN: your-gitlab-access-token"
      ]
    }
  }
}

Option 3: With Dynamic GitLab URL and Token

Copy & paste — that's it

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/client-cli",
        "http://your-server:3000/mcp",
        "--header", "Authorization: Bearer your-gitlab-access-token",
        "--header", "x-gitlab-url: https://gitlab.company.com"
      ]
    }
  }
}

Multi-tenant Usage: Each user can configure their own token and GitLab instance URL in their client configuration, allowing the same server instance to serve multiple users with different GitLab permissions and instances.

Smithery

Use directly on Smithery platform:

Copy & paste — that's it

smithery add @zephyr-mcp/gitlab

Or search "@zephyr-mcp/gitlab" in Smithery UI and add to your workspace.

Environment variables:

GITLAB_API_URL: Base URL of your GitLab API (required for stdio mode, optional for httpStream mode - can be provided via HTTP headers)
GITLAB_TOKEN: Access token for GitLab API authentication (required for stdio mode, optional for httpStream mode - can be provided via HTTP headers)
MCP_TRANSPORT_TYPE: Transport type (stdio/httpStream)
MCP_HOST: Server binding address for HTTP stream mode
MCP_PORT: HTTP port for HTTP stream mode
MCP_ENDPOINT: HTTP endpoint path for HTTP stream mode

Quick Start

Stdio Mode (Default)

Copy & paste — that's it

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with stdio transport (default)
bun run start

HTTP Stream Mode (Server Deployment)

Copy & paste — that's it

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with HTTP stream transport
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 bun run start

# Or using command line flag
bun dist/index.js --http-stream

Usage Examples

Direct HTTP API Usage

You can also interact with the MCP server directly via HTTP requests:

Copy & paste — that's it

# Example: Get user tasks using Bearer token
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-gitlab-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "Gitlab Get User Tasks Tool",
      "arguments": {
        "taskFilterType": "ASSIGNED_MRS",
        "fields": ["id", "title", "source_branch", "target_branch"]
      }
    }
  }'

Copy & paste — that's it

# Example: Search projects using PRIVATE-TOKEN header
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "PRIVATE-TOKEN: your-gitlab-token" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "Gitlab Search Project Details Tool",
      "arguments": {
        "projectName": "my-project",
        "fields": ["id", "name", "description", "web_url"]
      }
    }
  }'

Copy & paste — that's it

# Example: Use dynamic GitLab instance URL with Bearer token
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-gitlab-token" \
  -H "x-gitlab-url: https://gitlab.company.com" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "Gitlab Get User Tasks Tool",
      "arguments": {
        "taskFilterType": "ASSIGNED_MRS",
        "fields": ["id", "title", "source_branch", "target_branch"]
      }
    }
  }'

Tool Examples

For detailed examples of each tool's parameters, see USAGE.md.

Key benefits of HTTP Stream mode with dynamic authentication:

Multi-tenant support: Single server instance can serve multiple users
Security: Each request uses its own authentication token and GitLab instance URL
Flexibility: Tokens and GitLab URLs can be configured per client without server restart
Multi-instance support: Connect to different GitLab instances from the same server

Deployment

Docker Deployment

The repository includes a Dockerfile for easy deployment:

Copy & paste — that's it

# Build the Docker image
docker build -t gitlab-mcp-server .

# Run with environment variables (both token and URL can be provided via HTTP headers)
docker run -d \
  -p 3000:3000 \
  -e MCP_TRANSPORT_TYPE=httpStream \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=3000 \
  gitlab-mcp-server

Docker Compose Example

Copy & paste — that's it

services:
  gitlab-mcp:
    image: node:22.14.0
    container_name: gitlab-mcp
    ports:
      - "3000:3000"
    environment:
      - MCP_TRANSPORT_TYPE=httpStream
      - MCP_HOST=0.0.0.0
      - MCP_PORT=3000
      # Both GITLAB_API_URL and GITLAB_TOKEN are optional when using HTTP headers
      # - GITLAB_API_URL=https://your-gitlab-instance.com
      # - GITLAB_TOKEN=your_gitlab_token
    command: npx -y @zephyr-mcp/gitlab@latest

Important for Docker: When running in Docker containers, make sure to set MCP_HOST=0.0.0.0 to allow external access. The default value for httpStream transport is already 0.0.0.0, but setting it explicitly ensures compatibility.

Manual Deployment

Copy & paste — that's it

# Install dependencies and build
npm install
npm run build

# Start the server in HTTP stream mode
export GITLAB_API_URL=https://your-gitlab-instance.com
export GITLAB_TOKEN=your_access_token
export MCP_TRANSPORT_TYPE=httpStream
export MCP_PORT=3000

# Run the server
node dist/index.js

Process Manager (PM2)

Copy & paste — that's it

# Install PM2
npm install -g pm2

# Create ecosystem file
cat > ecosystem.config.js << EOF
module.exports = {
  apps: [{
    name: 'gitlab-mcp-server',
    script: 'dist/index.js',
    env: {
      GITLAB_API_URL: 'https://your-gitlab-instance.com',
      GITLAB_TOKEN: 'your_access_token',
      MCP_TRANSPORT_TYPE: 'httpStream',
      MCP_PORT: 3000
    }
  }]
}
EOF

# Start with PM2
pm2 start ecosystem.config.js
pm2 save
pm2 startup

mcp-gitlab MCP Server (English)

Features

Environment Variables

Transport Modes

1. Stdio Transport (Default)

2. HTTP Stream Transport

Authentication Methods

Project Structure

Integration

Claude Desktop Client

Stdio Mode (Default)

HTTP Stream Mode (Server Deployment)

Smithery

Related Links

Quick Start

Stdio Mode (Default)

HTTP Stream Mode (Server Deployment)

Usage Examples

Direct HTTP API Usage

Tool Examples

Deployment

Docker Deployment

Docker Compose Example

Manual Deployment

Process Manager (PM2)