中文版

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

Related Links

• fastmcp
• Smithery
• GitLab API