mcp-server-gitlab

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

GITLAB_API_URL=https://your-gitlab-instance.com
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

See USAGE.md for detailed examples of each tool's parameters.

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

When using HTTP Stream mode, clients can connect to:

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

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)

For remote server deployment, first start the server:

# On your server
MCP_TRANSPORT_TYPE=httpStream MCP_PORT=3000 npx @zephyr-mcp/gitlab

Then configure Claude Desktop with HTTP transport:

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

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
GITLAB_TOKEN: Access token for GitLab API authentication
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
docker run -d \
  -p 3000:3000 \
  -e GITLAB_API_URL=https://your-gitlab-instance.com \
  -e GITLAB_TOKEN=your_access_token \
  -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:
      - GITLAB_TOKEN=your_gitlab_token
      - GITLAB_API_URL=your-gitlab-instance.com
      - MCP_TRANSPORT_TYPE=httpStream
      - MCP_HOST=0.0.0.0
      - MCP_PORT=3000
    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

Deploy Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

MCP フレームワークに基づいて構築された GitLab 集合サーバーは、多数の GitLab RESTful API ツールを提供し、コンテンツの検索、タスク管理、コアなどの機能との結合および構築の要求をサポートし、高効率のアクションの実行を支援します。

Related Resources

Reddit Discussion about this server

Related MCP Servers

GitLab MCP Serverofficial
modelcontextprotocol
A
security
A
license
A
quality
MCP Server for the GitLab API, enabling project management, file operations, and more.
Last updated -
1,673
67,553
MIT License
gitlab-mcp-server
yoda-digital
A
security
A
license
A
quality
GitLab MCP Server (with activity tracking and group projects listing features) This server is based on the original GitLab MCP server with Group Projects Listing and Activity Tracking enhancements
Last updated -
28
75
27
MIT License
https://github.com/owayo/gitlab-mcp-server
owayo
A
security
A
license
A
quality
GitLabとの連携機能を提供するModel Context Protocol (MCP) サーバーです。GitLabの特定のプロジェクトからパイプラインの失敗情報やマージリクエストへの指摘事項を取得し、AIアシスタントに提供します。
Last updated -
3
3
MIT License
GitLab MCP Server
harshmaur
-
security
A
license
-
quality
An MCP server that enables communication with GitLab repositories, allowing interaction with GitLab's API to manage projects, issues, and repositories through natural language.
Last updated -
9,008
1
MIT License

View all related MCP servers

mcp-server-gitlab

mcp-gitlab MCP Server (English)

Features

Quick Start

Stdio Mode (Default)

HTTP Stream Mode (Server Deployment)

Environment Variables

Usage Examples

Transport Modes

1. Stdio Transport (Default)

2. HTTP Stream Transport

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)

Tools

Related Resources

Related MCP Servers

GitLab MCP Serverofficial

gitlab-mcp-server

https://github.com/owayo/gitlab-mcp-server

GitLab MCP Server

Appeared in Searches

New MCP Servers

MCP directory API

mcp-gitlab MCP Server (English)

Features

Quick Start

Stdio Mode (Default)

HTTP Stream Mode (Server Deployment)

Environment Variables

Usage Examples

Transport Modes

1. Stdio Transport (Default)

2. HTTP Stream Transport

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

Tools

Related Resources

Related MCP Servers

GitLab MCP Serverofficial

gitlab-mcp-server

https://github.com/owayo/gitlab-mcp-server

GitLab MCP Server

Appeared in Searches

New MCP Servers

MCP directory API