mcp-server-gitlab
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
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
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.
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
Quick Start
Stdio Mode (Default)
# Install dependencies
bun install
# Build the project
bun run build
# Start the server with stdio transport (default)
bun run startHTTP 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-streamEnvironment 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=/mcpUsage 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/jsonAuthentication 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-token2. Private Token Header:
POST http://localhost:3000/mcp
Content-Type: application/json
PRIVATE-TOKEN: your-gitlab-access-token3. Alternative Private Token Header:
POST http://localhost:3000/mcp
Content-Type: application/json
private-token: your-gitlab-access-token4. Custom GitLab Token Header:
POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-token: your-gitlab-access-tokenGitLab Instance URL Configuration:
1. GitLab URL Header (Recommended):
POST http://localhost:3000/mcp
Content-Type: application/json
x-gitlab-url: https://gitlab.company.com2. Alternative GitLab URL Headers:
POST http://localhost:3000/mcp
Content-Type: application/json
gitlab-url: https://gitlab.company.comPOST http://localhost:3000/mcp
Content-Type: application/json
gitlab-api-url: https://gitlab.company.com5. 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.comProject 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.jsonIntegration
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-serverClient 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/gitlabOr 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 modeMCP_PORT: HTTP port for HTTP stream modeMCP_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-serverDocker 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@latestImportant 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.jsProcess 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 startupRelated Links
Available Tools
8 toolsGitlab Accept MR ToolC
接受并合并指定项目的合并请求,支持自定义合并选项。
Inputs: mergeRequestId (required), projectId (required), fields, mergeOptions.
Gitlab Create MR Comment ToolC
为指定项目的合并请求添加评论。
Inputs: comment (required), mergeRequestId (required), projectId (required), fields.
Gitlab Create MR ToolC
创建新的 Merge Request,支持指派 assignee 和 reviewers。
Inputs: projectId (required), sourceBranch (required), targetBranch (required), title (required), +5 more.
Gitlab Get User Tasks ToolC
获取当前用户的待办任务,支持多种过滤条件。
Inputs: fields, taskFilterType.
Gitlab Raw API ToolB
支持自定义调用任意 GitLab REST API,适合调试和高级用法。
Inputs: endpoint (required), method (required), data, fields, +1 more.
Gitlab Search Project Details ToolC
根据项目名称搜索项目及其详细信息,支持字段过滤,提升响应效率。
Inputs: projectName (required), fields.
Gitlab Search User Projects ToolC
根据用户名搜索用户信息及其活跃项目。支持字段过滤,提升响应效率。
Inputs: username (required), fields.
Gitlab Update MR ToolC
更新指定项目的 Merge Request,包括指派 assignee 和 reviewers。
Inputs: mergeRequestId (required), projectId (required), assigneeId, description, +4 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes targeting specific GitLab resources like MRs, projects, users, and tasks. However, 'Gitlab Search Project Details Tool' and 'Gitlab Search User Projects Tool' could be slightly confused as both involve searching with filtering, though one focuses on projects and the other on users. Overall, descriptions clarify boundaries well.
Tool names follow a highly consistent pattern: all start with 'Gitlab', use a verb (e.g., Accept, Create, Get, Search, Update) followed by a noun phrase (e.g., MR Tool, User Tasks Tool), and maintain uniform capitalization and structure. This predictability aids agent selection.
With 8 tools, this server is well-scoped for GitLab operations. It covers core workflows like MR management, project/user search, and tasks, without being overly broad or sparse. Each tool serves a clear purpose, making the count appropriate for the domain.
The tool set provides good coverage for GitLab interactions, including MR lifecycle (create, update, accept, comment), project/user search, and task management. Minor gaps exist, such as no direct tools for listing repositories or handling issues, but the 'Gitlab Raw API Tool' offers a workaround for advanced or missing operations.
Maintenance
Related MCP Connectors
Go MCP server for GitLab: 2 dynamic tools reach 1000+ REST/GraphQL actions. Free/CE, no paid tier.
GitLab MCP — wraps the GitLab REST API v4 (BYO API key)
A MCP server built for developers enabling Git based project management with project and personal…
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for the GitLab API that enables comprehensive project management, file operations, and issue tracking. It supports automated branch creation, batch file pushes, and interaction with merge requests and CI/CD logs.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for interacting with GitLab API, supporting both self-hosted instances and gitlab.com. Provides tools for managing issues, merge requests, code review, pipelines, milestones, releases, search, and file access.2,012 npmMIT
- AlicenseNot gradedqualityBmaintenanceMCP server for the GitLab REST API providing tools to manage projects, merge requests, pipelines, CI/CD variables, approvals, issues, and code reviews.6,421 PyPI7MIT
- AlicenseCqualityBmaintenanceMCP server for interacting with GitLab API, supporting dynamic tool selection and enterprise-grade security.20810MIT