GitLab MCP Server

GitLab MCP サーバー（@sumirati/mcp-gitlab）

セルフホスト型の GitLab Community Edition（CE）、Enterprise Edition（EE）、および GitLab.com 向けに開発された、GitLab API v4 用の最新の 2026 年対応 AI ネイティブ Model Context Protocol（MCP）サーバーです。

---

v3.0.0 の特長：2026 年版 5 ツールのハイブリッド標準

初期の MCP サーバーでは、50〜100 個のツールをクライアントのツールリストに並べることで、毎ターン 10,000 個以上のプロンプトコンテキストトークン（「システムプロンプト税」）を消費し、Glama TDQS の評価基準で低い一貫性評価を招いていました。

@sumirati/mcp-gitlab v3 は、5 ツールのハイブリッド構成によりこの問題を解決します。

• Glama TDQS 一貫性ランク A（5/5）：クライアントに公開するツールをちょうど 5 個にすることで、サーバーは一貫性に理想的な 3〜15 個の範囲に収まります。
• 極めて軽量なシステムプロンプト税：スキーマのオーバーヘッドを約 11,200 トークンから約 450 トークンへ削減し（96% 削減）、コンテキストウィンドウを維持して LLM のプロンプトキャッシュヒットを最大化します。
• ホップなしで実行する使用頻度の高い操作：ペアプログラミング中に開発者やエージェントが頻繁に使う 3 つの操作（get_file_contents、get_project、get_commit）は、即時実行できるホップなしのツールとして引き続き利用できます。
• 必要に応じてプラットフォーム全体にアクセス：14 のドメインにまたがる 88 のアクションすべてに、動的なアクション検出（gitlab_find_actions $\rightarrow$ gitlab_execute_action）を通じて必要に応じてアクセスでき、既定の高密度 Markdown テーブルと要約（format: "markdown" | "json"）により、85%〜90% のトークンを削減します。
• 堅牢なフォールバック：エージェントがカタログ内のアクション名（例：list_pipelines）を直接呼び出した場合も、サーバーは入力の完全な検証とデータの絞り込みを行って、そのアクションを動的に実行します。

LLM Prompt Context (~450 tokens total):
├── 1. gitlab_find_actions(query, [domain], [format])     [Meta Discovery]
├── 2. gitlab_execute_action(action, params, [format])   [Meta Dynamic Execution]
├── 3. get_file_contents(projectId, filePath)             [Eager Daily Driver #1]
├── 4. get_project(projectId)                             [Eager Daily Driver #2]
└── 5. get_commit(projectId, sha)                         [Eager Daily Driver #3]

Under the hood (Dynamic Registry):
└── 88 Curated Actions across 14 Domains (with 85%–98% token reduction projections)

---

14 のドメインにわたる主な機能

1. エンタープライズ向け可観測性とセルフホスト運用：
   • システム健全性の診断：エンドツーエンドの接続、トークンの本人確認、API レイテンシのテスト（system_health_check）。
   • プッシュミラー：GitHub/GitLab.com への上流レプリケーションを確認し（list_push_mirrors）、即時同期を強制します（trigger_push_mirror_sync）。
   • CI ランナー：ランナーの健全性、オンライン／一時停止状態、タグを監査します（list_runners、get_runner_status）。
   • Webhook：登録済みの自動化フックを確認します（list_project_hooks）。
2. リポジトリとブランチのガバナンス：プロジェクトの CRUD、グループ階層の解決（buggycode/project-name）、ブランチのライフサイクル、ブランチ保護の管理（list_protected_branches、protect_branch、unprotect_branch）、ファイルの読み取り、複数ファイルのアトミックなコミット（push_files）。
3. CI/CD の可観測性：ステータスでパイプラインを検索し、失敗したジョブのログをトークン消費を抑えて末尾から取得し（get_job_trace）、ビルド成果物を読み取り、JUnit テストレポートを確認します。
4. マージリクエストのレビューと差分のディスカッション：2 段階の差分確認、自動的なロックファイルの整理（package-lock.json）、SHA 座標の解決を伴うインライン差分ディスカッション。
5. イシューとタスク計画：イシューの CRUD、ブロッカー／依存関係の追跡（issue_links）、進捗メモの追加（issue_notes）。
6. マイルストーンとラベル：人が読みやすいマイルストーンの解決、ラベルの作成、スコープ指定によるマイルストーンの確認。
7. Wiki とスニペット：ドキュメントのアウトライン分割（toc_only: true）、章の抽出、スニペットの管理。
8. ユーザーとアイデンティティのコンテキスト：認証済みユーザーの情報照会、グループの列挙、所有プロジェクトの検出。

---

クイックスタートとインストール

オプション 1：npx で実行（インストール不要）

npx -y @sumirati/mcp-gitlab

オプション 2：グローバルにインストール

npm install -g @sumirati/mcp-gitlab
mcp-gitlab

オプション 3：ローカルにクローン

git clone https://github.com/sumirati/mcp-gitlab.git
cd mcp-gitlab
npm install
npm test
npm start

---

環境設定

変数	必須	デフォルト	説明
GITLAB_PERSONAL_ACCESS_TOKEN	はい	—	api スコープを持つパーソナルアクセストークンです。
GITLAB_API_URL	いいえ	https://gitlab.com/api/v4	GitLab CE/EE またはクラウドインスタンスのベース API URL です。
GITLAB_READ_ONLY	いいえ	false	読み取り専用の安全モードを有効にします（true、1、yes）。変更を伴うツールを除外し、86 個すべてのアクションにおいて書き込み／変更を行う HTTP リクエストを厳格にブロックします。
GITLAB_EXPOSE_ALL_TOOLS	いいえ	false	5 ツールのハイブリッドサーフェスを無効にし、レガシークライアント向けに ListTools で 86 個すべてのツールを直接公開するには、true（または GITLAB_EXPOSE_LEGACY_TOOLS=true）を設定します。

---

クライアント設定

Google Antigravity / Claude Desktop / Cursor

MCP 設定ファイル（mcp_config.json または claude_desktop_config.json）に追加します。

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@sumirati/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<your-gitlab-token>",
        "GITLAB_API_URL": "https://gitlab.example.com/api/v4"
      }
    }
  }
}

---

全アクションカタログのリファレンス（82 アクション）

82 個すべてのアクションで、厳格な入力検証とフィールドマスクによるプロジェクションを利用できます（トークンを 77%～98% 削減）。

1. クライアントに公開される 5 つのツール（ハイブリッドモード）

ツール	種類	説明
gitlab_find_actions	メタ	コンパクトなパラメータースキーマを使用して、14 のすべてのドメインにわたる GitLab 操作を検索、確認します
gitlab_execute_action	メタ	入力検証とトークン最適化されたプロジェクションを使用して、確認済みの GitLab プラットフォームアクションを実行します
get_file_contents	即時	クローンせずに、任意のブランチまたはコミット参照からファイルの内容やディレクトリ一覧を読み取ります
get_project	即時	プロジェクトのメタデータ、プロジェクト ID、可視性、クローン URL、デフォルトブランチを取得します
get_commit	即時	Git コミットの詳細、作成者情報、トークン数を制限したファイル差分を確認します

2. エンタープライズおよびセルフホスト環境での操作（5 アクション）

アクション	説明	変更を伴う操作？
list_push_mirrors	プロジェクトのリモートプッシュミラーと同期状況を一覧表示します	いいえ
trigger_push_mirror_sync	プッシュミラーの同期を即時に強制実行します（例：ローカルのセルフホスト環境から GitHub へ）	はい
list_runners	CI/CD ランナーをオンライン／一時停止の状態とともに一覧表示します（インスタンス、グループ、プロジェクトの各レベル）	いいえ
get_runner_status	ランナーの詳細な健全性指標、アーキテクチャ、タグ、最終接続時刻を取得します	いいえ
list_project_hooks	設定済みのプロジェクト Webhook と登録されたイベントトリガーを一覧表示します	いいえ

3. リポジトリおよびプロジェクト管理（8 アクション）

アクション	説明	変更を伴う操作？
search_repositories	GitLab 全体、または特定のグループ内でプロジェクトを名前で検索します	いいえ
create_repository	個人またはグループの名前空間に新しいプロジェクトを作成します	はい
update_project	プロジェクトの表示名、説明、デフォルトブランチ、トピックを更新します	はい
delete_project	プロジェクトを完全に削除します（明示的な安全確認が必要です）	はい
create_or_update_file	即時の Git コミットを伴って、単一ファイルを作成または更新します	はい
push_files	複数のファイルの追加、編集、削除を 1 つのコミットでアトミックに実行します	はい
create_commit	push_files の別名です。GitLab Commits API を通じて複数のファイルをアトミックにコミットします	はい
fork_repository	既存のプロジェクトを、指定したユーザーまたはグループの名前空間にフォークします	はい

4. ブランチガバナンス（4 アクション）

アクション	説明	変更を伴う操作？
list_branches	最新のコミット概要と保護状態を含めて、リポジトリのブランチを一覧表示します	いいえ
get_branch	コミット作成者や保護状態を含む、特定のブランチの詳細を取得します	いいえ
create_branch	既存のブランチ、タグ、または SHA を起点として新しいブランチを作成します	はい
delete_branch	Git ブランチを削除します（デフォルトブランチの削除は厳格にブロックされます）	はい

5. Git コミットと履歴（1 アクション）

アクション	説明	変更を伴う？
list_commits	ブランチ、日付、またはファイルパスで絞り込んだ、時系列順のコミット履歴を一覧表示します	いいえ

6. パイプラインと CI/CD の可観測性（8 アクション）

アクション	説明	変更を伴う？
list_pipelines	ブランチ、コミット SHA、または実行ステータスで絞り込んだパイプラインを一覧表示します	いいえ
get_pipeline	パイプラインの実行詳細、所要時間、全体のステータスを取得します	いいえ
create_pipeline	指定したブランチまたはタグで新しい CI/CD パイプラインを実行します	はい
cancel_pipeline	実行中のパイプラインをキャンセルします	はい
retry_pipeline	パイプライン実行で失敗またはキャンセルされたジョブを再試行します	はい
list_pipeline_jobs	ステージ、ステータス、所要時間とともに、パイプライン内の個々のジョブを一覧表示します	いいえ
get_job_trace	コンテキストの過剰な消費を防ぐため、行数を制限してジョブのビルド／テストログを安全に末尾から取得します	いいえ
get_job_artifact_file	完了したジョブのビルド成果物から特定のファイルを読み取ります	いいえ

7. マージリクエストとコードレビュー（12 アクション）

アクション	説明	変更を伴う？
list_merge_requests	状態（opened、merged、closed）、ソース／ターゲットで絞り込んだプロジェクトの MR を一覧表示します	いいえ
get_merge_request	MR の詳細なメタデータ、マージ可能性、ブランチ情報を取得します	いいえ
create_merge_request	ソースブランチ、ターゲットブランチ、説明を指定して新しい MR を作成します	はい
update_merge_request	タイトル、説明、ターゲットブランチ、またはドラフト状態を更新します	はい
accept_merge_request	オプションでスカッシュやブランチ削除を指定して、承認済みの MR をマージします	はい
get_merge_request_changes	ロックファイルのフィルタリングと行の切り詰めによる安全対策を備えた、2 段階の差分レビューを行います	いいえ
list_merge_request_diffs	コミット差分のバージョンと座標 SHA（head_sha、base_sha）を一覧表示します	いいえ
list_merge_request_discussions	コードレビューのディスカッションとコメントスレッドを一覧表示します	いいえ
create_diff_discussion	特定のファイルと行の差分に紐づけて、インラインのレビューコメントを作成します	はい
reply_merge_request_discussion	既存のレビューコメントスレッドに返信します	はい
resolve_merge_request_discussion	インラインのレビューコメントスレッドを解決済み、または再オープンとしてマークします	はい
update_merge_request_discussion_note	既存のレビューコメントを編集します	はい

8. イシューとロードマップ（8 アクション）

アクション	説明	変更を伴う？
list_issues	状態、マイルストーン、ラベル、作成者、または担当者で絞り込んだイシューを一覧表示します	いいえ
get_issue	イシューの詳細、説明、担当者、状態を取得します	いいえ
create_issue	タイトル、説明、マイルストーン、ラベルを指定して新しいイシューを作成します	はい
update_issue	タイトル、説明、状態（close／reopen）、または担当者を変更します	はい
delete_issue	イシューを完全に削除します（安全確認が必要です）	はい
list_issue_notes	イシューのコメントを一覧表示します	いいえ
create_issue_note	イシューに進捗状況やコメントを投稿します	はい
create_issue_link	関係（relates_to、blocks、is_blocked_by）を指定してイシューをリンクします	はい

9. マイルストーンとラベル（6 アクション）

アクション	説明	変更を伴う？
list_milestones	プロジェクトのマイルストーンを一覧表示します（継承されたグループのマイルストーンも含みます）	いいえ
get_milestone	タイトルまたは数値 ID でマイルストーンの詳細を取得します	いいえ
create_milestone	タイトル、説明、期日を指定して新しいマイルストーンを作成します	はい
update_milestone	マイルストーンのタイトル、説明、状態、または日付を更新します	はい
list_labels	色と説明を含むプロジェクトのラベルを一覧表示します	いいえ
create_label	名前とカラーの HEX コードを指定して、新しいプロジェクトラベルを作成します	はい

10. リリースとタグ（5 アクション）

アクション	説明	変更を伴うか
list_releases	変更履歴とリリースアセットを含むプロジェクトのリリース一覧を取得します	いいえ
get_release	指定したリリースのリリースノートとタグのメタデータを取得します	いいえ
create_release	Markdown 形式のリリースノートを付けて、Git タグに紐づくリリースを作成します	はい
list_tags	コミットハッシュと注釈付きメッセージを含む Git タグの一覧を取得します	いいえ
create_tag	ブランチまたはコミット SHA を指す新しい Git タグを作成します	はい

11. プロジェクトのコラボレーターとロール（5 アクション）

アクション	説明	変更を伴うか
list_members	アクセスレベル（ゲストからオーナーまで）を含むプロジェクトメンバーの一覧を取得します	いいえ
get_member	指定したユーザーのメンバーシップの詳細とアクセスレベルを取得します	いいえ
add_member	ロール名または数値レベルを指定してコラボレーターを追加します	はい
update_member	コラボレーターのロールまたは有効期限を変更します	はい
remove_member	プロジェクトへのコラボレーターのアクセス権を削除します	はい

12. CI/CD 環境変数（5 アクション）

アクション	説明	変更を伴うか
list_variables	プロジェクトのパイプライン変数一覧を取得します（値はマスクされます）	いいえ
get_variable	変数の詳細を取得し、値を復号します	いいえ
create_variable	マスク／保護フラグを指定して変数（env_var または file）を作成します	はい
update_variable	変数の値、マスキング、または保護状態を更新します	はい
delete_variable	パイプライン変数を削除します	はい

13. Wiki とドキュメント（4 アクション）

アクション	説明	変更を伴うか
list_wikis	プロジェクト内のすべての Wiki ページを一覧表示します	いいえ
get_wiki	目次（toc_only）またはセクション抽出を指定して Wiki の内容を取得します	いいえ
create_wiki	タイトルと Markdown コンテンツを指定して新しい Wiki ページを作成します	はい
update_wiki	既存の Wiki ページのタイトルまたは Markdown コンテンツを更新します	はい

14. スニペットとユーザーコンテキスト（9 アクション）

• スニペット：list_snippets、get_snippet、create_snippet、update_snippet。
• ユーザーとグループ：get_current_user、list_my_groups、get_group、list_group_projects、list_my_projects。

---

ベンチマーク：トークン節約の実例

操作	標準の GitLab API	@sumirati/mcp-gitlab	トークン削減率
システムプロンプトの負荷（5 ツール対 88 アクション）	約14,200トークン	約450トークン	96.8%節約
get_project（単一プロジェクトの調査）	1,850トークン	210トークン	88.6%節約
list_merge_requests（10 件の MR）	8,900トークン	940トークン	89.4%節約
list_pipelines（10 件の実行）	4,200トークン	620トークン	85.2%節約
get_merge_request_changes（差分レビュー）	48,000トークン以上	約3,200トークン	93.3%節約

主なトークン最適化の柱：

• スマートな差分処理とロックファイルの切り詰め：コミット差分（get_commit）と MR の変更内容（get_merge_request_changes）では、デフォルトで ignore_lockfiles: true により、依存関係のロックファイル（package-lock.json、pnpm-lock.yaml、yarn.lock、go.sum、Cargo.lock、*.min.js）を自動的に折りたたみます。これにより、レビューごとに1,000～3,000トークンを節約できます。ロックファイルの差分全体が必要な場合は、ignore_lockfiles: false を渡してください。
• 控えめなデフォルトのページネーション：すべての一覧アクションでは、デフォルトで per_page: 10（最大：100）を使用します。これにより、必要なのは最新の項目だけなのに20～50件を読み込むことで生じるトークンの無駄をなくします。
• 高密度な Markdown 形式をデフォルトに設定：検出（gitlab_find_actions）、実行（gitlab_execute_action）、プロジェクト情報（get_project）、コミットの調査（get_commit）では、デフォルトで format: "markdown" を使用し、生の JSON と比べてトークンを85～90%削減します。
• 再帰的な出力投影フィルター（projectOutput）：ペイロードが LLM のコンテキストに渡される前に、ノイズとなるメタデータキー（_links、avatar_url、gravatar_id、node_id、site_admin、ナビゲーション URL、内部 API リンク、null／空のフィールド）を除去します。

---

ロードマップ

今後の予定（v3.2）

• 上流のインデックス付きフィルタリングと厳格なページネーション上限（state、labels、milestone、author_id、assignee_id）
• クライアントのエラー耐性（401 プローブの判別、403 スコープ不足、429 レート制限時のバックオフ、201 のゴースト書き込み防止）
• 再帰深度ガード（maxDepth = 32）と空のコレクションの保持による、出力射影の強化
• ネストされたサブグループ階層の管理（parent_id を指定した create_group）
• get_job_trace での CI/CD 失敗ログのスマート抽出と ANSI シーケンスの除去（strip_ansi、smart_failure）
• get_file_contents でのアウトライン優先のコードシンボル抽出と行範囲の切り出し（outline_only、start_line、end_line）
• マージ可能性と競合の事前検証（get_mergeability）
• トークンスコープのセルフ監査と権限の事前確認

今後の展望（v3.x）

• LiteLLM / Eigent のエージェントオーケストレーションで複数ターンの履歴を整理しやすくする、コレクションの標準化された _summary ヘッダー
• リモートトランスポート：ストリーミング可能な SSE と HTTP リモートサーバーモード
• リレーションを深く調査する、スコープ制限付き GraphQL クエリエンジン
• DevSecOps の脆弱性およびシークレットスキャンアラートのクエリ
• プロジェクトリポジトリ内でのスコープ制限付き、レートガード付きコード検索

---

謝辞と由来

このプロジェクトには、以下のプロジェクトのアーキテクチャ概念、スキーマ、パターンが取り入れられています。

• @modelcontextprotocol/server-gitlab（MIT License）— Copyright (c) 2024 Anthropic, PBC / GitLab, PBC。ベースとなるリポジトリおよびファイルのスキーマパターン。
• @modelcontextprotocol/sdk（MIT License）— Copyright (c) Anthropic, PBC.
• zod（MIT License）— Colin McDonnell.
• GitLab REST API v4 — GitLab, PBC.
• jmrplens/gitlab-mcp-server — 動的なアクション検出とメタディスパッチャーパターンの概念。
• Vijay-Duke/mcp-gitlab と zereight/gitlab-mcp のアーキテクチャパターンを評価しました。

サードパーティの完全な帰属表示については、NOTICE を参照してください。

---

ライセンス

このプロジェクトは MIT License の下でライセンスされています — Copyright (c) 2026 [email protected]。