What can you do with this server?

mcp-server-gitlab is a GitLab integration server that provides tools to interact with GitLab's RESTful API. Key capabilities include: * Search users and projects: Retrieve active projects and user information by username * Manage Merge Requests: Create, approve, merge, and update merge requests with options for assignees, reviewers, and custom settings * Add comments: Insert comments into merge requests for better collaboration * Retrieve user tasks: Fetch pending tasks for the current user with various filtering options * Search project details: Find detailed project information by project name * Custom API usage: Directly interact with any GitLab API endpoint using custom parameters for advanced use cases

Which integrations are available for this server?

Utilizes Bun as the JavaScript runtime environment for building and running the MCP server. Provides tools for interacting with GitLab's RESTful API, enabling searching users and projects, managing tasks, creating and updating merge requests, adding comments, and executing custom API calls.

How do I use mcp-server-gitlab?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-server-gitlab search my recent merge requests and show their status" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

中文版

Build Status Node Version License

Downloads npm version

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

Related MCP server: gitlab-mcp-server

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

Install Server

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

Resources

Need Help?

Report Issue

Reddit Discussion

Related Servers

mcp-server-gitlab

mcp-gitlab MCP Server (English)

Features

Quick Start

Stdio Mode (Default)

HTTP Stream Mode (Server Deployment)

Environment Variables

Usage Examples

Direct HTTP API Usage

Tool Examples

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

Deployment

Docker Deployment

Docker Compose Example

Manual Deployment

Process Manager (PM2)

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API

mcp-gitlab MCP Server (English)

Features

Quick Start

Stdio Mode (Default)

HTTP Stream Mode (Server Deployment)

Environment Variables

Usage Examples

Direct HTTP API Usage

Tool Examples

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

Deployment

Docker Deployment

Docker Compose Example

Manual Deployment

Process Manager (PM2)

Related Links

Resources

Tools

Appeared in Searches

Latest Blog Posts

MCP directory API