mcp-gitlab MCP Server (English)

中文版

mcp-gitlab MCP サーバー（英語）

fastmcp フレームワーク上に構築された GitLab 統合サーバーで、さまざまな GitLab RESTful API ツールを提供します。Claude、Smithery などのプラットフォームとの統合をサポートしています。

機能

• GitlabSearchUserProjectsTool：ユーザー名でユーザーとそのアクティブなプロジェクトを検索します
• GitlabGetUserTasksTool：現在のユーザーの保留中のタスクを取得します
• GitlabSearchProjectDetailsTool：プロジェクトとその詳細を検索します
• GitlabCreateMRCommentTool：マージリクエストにコメントを追加します
• GitlabAcceptMRTool：マージリクエストを承認してマージします
• GitlabUpdateMRTool：マージリクエストの担当者、レビュアー、タイトル、説明、ラベルを更新します
• GitlabCreateMRTool：担当者とレビュアーを指定して新しいマージリクエストを作成します
• GitlabRawApiTool：カスタムパラメーターを使用して任意の GitLab API を呼び出します

クイックスタート

Stdio モード（デフォルト）

# Install dependencies
bun install

# Build the project
bun run build

# Start the server with stdio transport (default)
bun run start

HTTP Stream モード（サーバーデプロイ）

# 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

環境変数

# 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

使用例

HTTP API の直接使用

HTTP リクエストを使用して MCP サーバーと直接やり取りすることもできます。

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

ツールの例

各ツールのパラメーターの詳細な例については、USAGE.md を参照してください。

動的認証を使用する HTTP Stream モードの主な利点：

• マルチテナント対応：1 つのサーバーインスタンスで複数のユーザーにサービスを提供できます
• セキュリティ：各リクエストで独自の認証トークンと GitLab インスタンス URL を使用します
• 柔軟性：サーバーを再起動せずに、クライアントごとにトークンと GitLab URL を設定できます
• 複数インスタンス対応：同じサーバーから異なる GitLab インスタンスに接続できます

トランスポートモード

このサーバーは、2 つのトランスポートモードをサポートしています。

1. Stdio トランスポート（デフォルト）

• ローカル開発や MCP クライアントとの直接統合に最適です
• stdin/stdout を使用して通信します
• ネットワーク設定は不要です

2. HTTP Stream トランスポート

• リモートアクセス用のサーバーデプロイを可能にします
• ストリーミング応答を伴う HTTP POST リクエストを使用します
• 複数のクライアントが同じサーバーインスタンスに接続できます
• 本番環境へのデプロイに最適です
• HTTP ヘッダーによる動的なトークン認証をサポートします

HTTP Stream モードを使用する場合、クライアントは次の場所に接続できます。

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

認証方法

HTTP Stream モードでは、GitLab トークンとインスタンス URL を複数の方法で指定できます。

トークン認証：

1. Bearer トークン（推奨）：

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

2. Private Token ヘッダー：

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

3. 代替 Private Token ヘッダー：

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

4. カスタム GitLab トークンヘッダー：

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

GitLab インスタンス URL の設定：

1. GitLab URL ヘッダー（推奨）：

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

2. 代替 GitLab URL ヘッダー：

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. 環境変数へのフォールバック： ヘッダーにトークンまたは URL が指定されていない場合、サーバーは GITLAB_TOKEN と GITLAB_API_URL の環境変数にフォールバックします。

完全な例：

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

プロジェクト構成

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

統合

Claude デスクトップクライアント

Stdio モード（デフォルト）

設定に追加します。

{
  "mcpServers": {
    "@zephyr-mcp/gitlab": {
      "command": "npx",
      "args": ["-y", "@zephyr-mcp/gitlab"]
    }
  }
}

HTTP ストリームモード（サーバーのデプロイ）

サーバーのセットアップ： まずサーバーを起動します（HTTP ヘッダーを使用する場合、GITLAB_TOKEN と GITLAB_API_URL はどちらも省略可能です）。

# 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

クライアントの設定：

オプション 1：ベアラートークンを使用（推奨）

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

オプション 2：プライベートトークンヘッダーを使用

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

オプション 3：GitLab の URL とトークンを動的に指定

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

マルチテナントでの使用： 各ユーザーはクライアントの設定で独自のトークンと GitLab インスタンスの URL を設定できます。これにより、同じサーバーインスタンスで、異なる GitLab の権限やインスタンスを持つ複数のユーザーにサービスを提供できます。

Smithery

Smithery プラットフォームで直接使用できます。

smithery add @zephyr-mcp/gitlab

または、Smithery UI で「@zephyr-mcp/gitlab」を検索して、ワークスペースに追加してください。

環境変数：

• GITLAB_API_URL：GitLab API のベース URL（stdio モードでは必須、httpStream モードでは省略可能。HTTP ヘッダーで指定できます）
• GITLAB_TOKEN：GitLab API 認証用のアクセストークン（stdio モードでは必須、httpStream モードでは省略可能。HTTP ヘッダーで指定できます）
• MCP_TRANSPORT_TYPE：トランスポートの種類（stdio/httpStream）
• MCP_HOST：HTTP ストリームモードのサーバーバインドアドレス
• MCP_PORT：HTTP ストリームモードの HTTP ポート
• MCP_ENDPOINT：HTTP ストリームモードの HTTP エンドポイントパス

デプロイ

Docker でのデプロイ

このリポジトリには、簡単にデプロイできるよう Dockerfile が含まれています。

# 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 の例

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

Docker での重要事項： Docker コンテナで実行する場合は、外部からアクセスできるよう MCP_HOST=0.0.0.0 を設定してください。httpStream トランスポートのデフォルト値はすでに 0.0.0.0 ですが、明示的に設定することで互換性を確保できます。

手動でのデプロイ

# 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

プロセスマネージャー（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

関連リンク

• fastmcp
• Smithery
• GitLab API