Advanced GitLab MCP server

高度な GitLab MCP サーバー

高度な GitLab MCP サーバー — 26 種類のエンティティにわたる 234 の GitLab 操作を提供する、64 個の CQRS ツールを備えています。ツールカタログとパラメーターは、各インスタンスの GitLab バージョン、ティア、トークンスコープに応じて絞り込まれるため、エージェントには接続先のインスタンスが実際にサポートする機能のみが表示されます。

パッケージ

これは 2 つの npm パッケージを含むモノレポです。

• @structured-world/gitlab-mcp — MCP サーバーです。OAuth セッションをメモリおよびファイルに保存し、データベースへの依存はありません。ほとんどのユーザーにはこちらで十分です。
• @structured-world/gitlab-mcp-db — ロードバランサー配下で複数のレプリカを実行するための、オプションの PostgreSQL/Prisma OAuth セッションバックエンドです。OAUTH_STORAGE_TYPE=postgresql で有効にできます。セットアップの詳細はPostgreSQL デプロイガイドをご覧ください。

クイックスタート

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@structured-world/gitlab-mcp"],
      "env": {
        "GITLAB_TOKEN": "your_gitlab_token",
        "GITLAB_API_URL": "https://gitlab.com"
      }
    }
  }
}

要件： Node.js >= 24

主な特長

• 64 個のツールで 26 種類のエンティティに対応 — プロジェクト、マージリクエスト、パイプライン、作業項目、Wiki など
• CQRS アーキテクチャ — クエリには browse_*、コマンドには manage_* を使用
• 接続の回復性 — 起動時間の上限設定、指数バックオフによる自動再接続、GitLab に接続できない場合の切断モード
• 複数インスタンス対応 — GitLab.com、セルフマネージド、セルフホスト可能なインスタンスに、インスタンスごとの OAuth とレート制限を適用して接続できます。1 つの接続に複数のアカウントを紐付けることができ、たとえば会社の GitLab と個人用の GitLab.com アカウントを登録し、チャットごとに切り替えて利用できます
• 複数のトランスポート — stdio、SSE、StreamableHTTP
• OAuth 2.1 — Claude Custom Connector によるユーザーごとの認証
• 読み取り専用モード — 本番環境でも安全に運用
• 自動検出 — git remote から GitLab の設定を検出
• きめ細かな制御 — ツールグループの有効化／無効化、アクションの絞り込み、説明のカスタマイズ
• Docker 対応 — ghcr.io/structured-world/gitlab-mcp:latest

ツールモデル

GitLab は数百の API 操作を公開しています。それぞれに独自の MCP ツールを割り当てるとエージェントのコンテキストが溢れ、薄い API ラッパーではその複雑さをエージェントに押し戻すことになります。このサーバーは別の方法を採用しています。64 個の CQRS ツールがそれぞれ複数の型付きアクションを備え、26 種類のエンティティにわたる 234 個の操作を公開します。

• browse_* ツールは読み取り専用のクエリ、manage_* ツールは書き込みを行います。
• サブリソースは新しいツールではなくアクションにまとめられます。たとえば、browse_pipelines はパイプライン、ジョブ、ログを 1 つのツールで扱います。
• ツール一覧、アクション、パラメーターは、GitLab のバージョン、ティア、トークンのスコープ、管理者モード、機能フラグ、プロファイルに基づき、スキーマ生成時に解決されます。

例：

• browse_pipelines — 一覧表示、取得、ジョブ、ジョブ詳細、ログ、トリガー
• manage_pipeline — 作成、再試行、キャンセル
• browse_environments — 一覧表示、取得、デプロイ一覧表示
• manage_environment — 作成、更新、停止、削除、デプロイステータスの更新
• browse_deploy_keys / manage_deploy_key — 一覧表示、取得 / 追加、有効化、更新、削除

ドキュメント

詳細なドキュメントは gitlab-mcp.sw.foundation でご覧いただけます。

セクション	説明
インストール	npm、Docker、VS Code、Codex
設定	環境変数、機能フラグ
マルチインスタンス	複数の GitLab インスタンスへの接続
ツールリファレンス	パラメーター付きの 64 個すべてのツール
OAuth の設定	Claude を使ったチーム認証
TLS/HTTPS	SSL を使った本番環境へのデプロイ
カスタマイズ	ツールの説明、アクションのフィルタリング
CLI ツール	ツールドキュメントの閲覧とエクスポート

自動生成されるツールリファレンス

パラメーターを含むツールリファレンス全体については、以下をご覧ください。

# View locally
yarn list-tools --detail

# Generate documentation
yarn list-tools --export --toc > docs/tools/api-reference.md

自動生成されるツールドキュメントについては、API リファレンス全文をご覧ください。

Docker

# HTTP mode
docker run -e PORT=3002 -e GITLAB_TOKEN=your_token -p 3333:3002 \
  ghcr.io/structured-world/gitlab-mcp:latest

# stdio mode
docker run -i --rm -e GITLAB_TOKEN=your_token \
  ghcr.io/structured-world/gitlab-mcp:latest

接続の回復性

サーバーはGitLabの接続問題を適切に処理します。

• 起動時間の上限 — GitLabが利用可能かどうかにかかわらず、サーバーはGITLAB_INIT_TIMEOUT_MS（既定値は5s）以内に起動します
• 切断モード — GitLabに接続できない場合（disconnected／failed状態）、診断用のwhoami、switch_preset、set_scopeなどのローカル操作を含むmanage_contextツールのみが公開されます。再接続中（connecting状態）は、短時間の停止中にMCPクライアントがツールカタログを失わないよう、ツールの全リストを引き続き利用できます。ツールの利用可否の変更は、tools/list_changedを通じてMCPクライアントに通知されます
• 自動再接続 — 指数バックオフによる再接続（5s → 60s、ジッターは±10%）
• エラー分類 — 一時的なエラー（ネットワーク、5xx、タイムアウト）が発生すると、自動再接続が行われます。起動時の認証／設定エラーではfailed状態に移行し、自動再接続は行われません。セッション中のトークン失効は、定期的なヘルスチェックと同時に実行される認証済みのHEAD /api/v4/userチェックによって検出されます（静的トークンモードのみ。OAuthモードでは省略されます）。このチェックで401または403が返された場合、インスタンスは直ちにfailed状態に移行します。
• インスタンスのヘルスモニター — 監視対象の各インスタンスURLには、独自のXStateステートマシンがあります。追跡対象外のOAuth URLは、現時点では到達可能として扱われます。

変数	既定値	説明
GITLAB_INIT_TIMEOUT_MS	5000	起動時にGitLabを待機する最大時間
GITLAB_RECONNECT_BASE_DELAY_MS	5000	初回の再接続待ち時間（試行ごとに倍増）
GITLAB_RECONNECT_MAX_DELAY_MS	60000	再接続待ち時間の最大値
GITLAB_HEALTH_CHECK_INTERVAL_MS	60000	接続中のヘルスチェック間隔
GITLAB_FAILURE_THRESHOLD	3	切断に至るまでの一時的な連続失敗回数
GITLAB_TOOL_TIMEOUT_MS	120000	ツール／ブートストラップの実行がタイムアウトするまでの最大時間
GITLAB_RESPONSE_WRITE_TIMEOUT_MS	10000	ゾンビ接続を破棄する前に、SSE以外のレスポンスをフラッシュする最大時間（無効にするには0を指定。SSEではハートビートを使用）
GITLAB_INSTANCE_CACHE_MAX	100	メモリに保持するURLごとのインスタンス状態の最大数（OAuthマルチテナント。上限を超えるとLRU方式で削除）
GITLAB_INSTANCE_TTL_MS	3600000	アイドル状態のURLごとのインスタンス状態のTTL（ms）。次回挿入時に削除されます（OAuthマルチテナント）

機能フラグ

フラグ	既定値	有効になるツール
USE_LABELS	true	ラベル管理
USE_MRS	true	マージリクエスト
USE_FILES	true	ファイル操作
USE_VARIABLES	true	CI/CD変数
USE_WORKITEMS	true	イシュー、エピック、タスク
USE_WEBHOOKS	true	Webhook管理
USE_SNIPPETS	true	コードスニペット
USE_INTEGRATIONS	true	50以上のインテグレーション
USE_GITLAB_WIKI	true	Wikiページ
USE_MILESTONE	true	マイルストーン
USE_PIPELINE	true	パイプラインとCI/CD
USE_RELEASES	true	リリース管理
USE_REFS	true	ブランチとタグの管理
USE_MEMBERS	true	チームメンバー
USE_SEARCH	true	プロジェクト横断検索
USE_ITERATIONS	true	イテレーション計画（スプリント）
USE_CI_TOKENS	true	CIアクセス認証情報：ジョブトークンのスコープとデプロイキー
USE_ENVIRONMENTS	true	環境とデプロイ
USE_RUNNERS	true	CIランナー管理
USE_REGISTRY	true	コンテナレジストリのリポジトリとタグ
USE_ACCESS_TOKENS	true	プロジェクト／グループ／個人アクセストークンの管理
USE_AUDIT_EVENTS	true	監査イベント（Premium以上）
USE_VULNERABILITIES	true	脆弱性管理（Ultimate）

貢献

開発環境のセットアップ、テスト、PRのガイドラインについては、CONTRIBUTING.mdを参照してください。

プロジェクトを支援する

## License

Apache License 2.0 — see LICENSE for details.

Based on zereight/gitlab-mcp (MIT). See LICENSE.MIT.