中文版

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

Quick Start

Stdio Mode (Default)

# 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)

# 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

Environment Variables

# 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

Usage Examples

Direct HTTP API Usage

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

# 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"]
      }
    }
  }'

# 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"]
      }
    }
  }'

# 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

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:

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):

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

2. Private Token Header:

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

3. Alternative Private Token Header:

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

4. Custom GitLab Token Header:

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):

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

2. Alternative GitLab URL Headers:

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

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:

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

Project Structure

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:

{
  "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):

# 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)

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

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

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

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

Deployment

Docker Deployment

The repository includes a Dockerfile for easy deployment:

# 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

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

# 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)

# 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

Related Links

• fastmcp
• Smithery
• GitLab API