GitLab MCP Server

GitLab MCP Server

GitLab 向けの最も包括的な Model Context Protocol（MCP）サーバー — 86 個のツール、エンタープライズ対応、活発にメンテナンスされています。

---

概要

GitLab MCP Server を使うと、AI エージェント（Claude Desktop、Claude Code、Cursor、Zed、VS Code、または任意の Model Context Protocol クライアント）が GitLab と直接やり取りできます。GitLab REST API への型付け、ページネーション、スキーマ検証に対応したブリッジであり、86 個の MCP ツールとして提供されます。glab をラップしたものではなく、画面のスクレイピングも行いません。

gitlab.com または任意のセルフホスト型 GitLab インスタンスで動作し、パーソナルアクセストークン、上流ゲートウェイから転送される OAuth Bearer トークン、または安全なデモ用の読み取り専用トークンで認証できます。

---

開発の背景

Anthropic は 2024 年 11 月 25 日に MCP を公開しました。リファレンスサーバーは Google Drive、Slack、GitHub、Git、Postgres、Puppeteer に対応していましたが、GitLab サーバーはありませんでした。Yoda Digital のエンジニアリングチームはセルフホスト型 GitLab を使用しているため、公式のサンプルは役に立たず、初期のコミュニティ版も GitLab の機能領域を十分にカバーできていませんでした。

そこで、自分たちのために開発しました。グループプロジェクト、アクティビティの追跡、そして DevOps チームが実際に必要としていた運用機能です。2025 年 3 月 18 日にオープンソースとして公開しましたが、役に立つと思う人が 5 人ほど見つかればよいと考えていました。

プロジェクトは 1 年で 86 個のツールを備え、stdio／SSE／Streamable HTTP トランスポート、PAT および OAuth モード、ghcr.io の Docker イメージ、そしてほぼすべてを面識のなかった外部コントリビューターが作成した Helm チャートを提供するようになりました。リリース 0.4.0 と 0.5.0 のコードは、今ではほとんど他の人が書いたものです。これはオープンソースのメンテナーにとって、最高の悩みです。

---

クイックスタート

ローカルクライアント（stdio）

Claude Desktop、Cursor、Zed、および MCP サーバーをローカルのサブプロセスとして実行する任意のクライアント向けです。クライアントの MCP 設定に以下を追加してください（Claude Desktop の場合は claude_desktop_config.json です）。

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@yoda.digital/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-…",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

セルフホスト環境ですか？GITLAB_API_URL をインスタンスの URL（例：https://gitlab.example.com/api/v4）に置き換えてください。書き込みアクセスなしで安全にデモを行うには、"GITLAB_READ_ONLY_MODE": "true" を追加してください。IDE ごとの説明は docs/CURSOR_INTEGRATION.md にあります。

リモート（Streamable HTTP、OAuth 認証必須）

共有デプロイメントや最新のリモート MCP クライアント向けに、サーバーを HTTP サービスとして実行します。ネットワークに公開するデプロイメントでは、AUTH_MODE=oauth が必要です。非ループバックのバインドで AUTH_MODE=pat を指定すると、サーバーは起動を拒否します。脅威モデルについては、SECURITY.md を参照してください。

docker run --rm -p 3000:3000 \
  -e HOST=0.0.0.0 \
  -e AUTH_MODE=oauth \
  -e USE_STREAMABLE_HTTP=true \
  ghcr.io/yoda-digital/mcp-gitlab-server:latest

次に、接続ごとに Authorization: Bearer <token> を挿入するゲートウェイをコンテナの前段に配置します。サーバーは、その Bearer を接続ごとの PAT として GitLab に転送します。クライアントの接続先には http://your-gateway/mcp を指定してください。

運用の詳細、プローブの設定、トラブルシューティングについては、docs/OPERATIONS.md を参照してください。

---

同梱されている機能

86 個のツールを、対象ごとに分類しています。

• リポジトリ：検索、作成、フォーク、プロジェクトのメタデータの取得と更新。
• ファイルとブランチ：ファイルの読み取り、作成、更新、削除、複数ファイルのコミット、ブランチ（一覧表示、作成、削除）、リポジトリツリー。
• タグとリリース：タグの一覧表示と作成、リリースの一覧表示と作成。
• イシュー：作成、一覧表示、更新、ノート、スレッド形式のディスカッション。
• マージリクエスト：作成、更新、マージ、リベース、承認、自動マージ、ノート、ディスカッション、変更、コミット。
• CI/CD：パイプライン（一覧表示、取得、トリガー、再試行、キャンセル）、ジョブ（一覧表示、取得、ログ、再試行、キャンセル）、環境。
• Wiki：添付ファイルを含む、プロジェクトおよびグループの Wiki。
• グループとメンバー：グループの CRUD、サブグループ、プロジェクトおよびグループのメンバー。
• ラベルとマイルストーン：一覧表示、作成、更新。保護ブランチ：一覧表示、保護、保護解除。
• ユーザーとメタ情報：現在のユーザー、ユーザーの一覧表示と取得、プロジェクトのイベント、コミット履歴。

ツールの全一覧は CLAUDE.md を参照してください。選択したツールの個別ドキュメントは docs/api/ にあります。

読み取り専用モード（GITLAB_READ_ONLY_MODE=true）では、登録時にすべての変更系ツールが除外されます。動作に問題のあるエージェントは、それらのツールを確認することすらできず、呼び出すこともできません。

---

トランスポート

トランスポート	使用する場面	フラグ
stdio	ローカルクライアント（Claude Desktop、Cursor、Zed）。デフォルトです。	(default)
SSE	従来の SSE 仕様を使用しているリモートクライアント。	USE_SSE=true
Streamable HTTP	現行の MCP Streamable HTTP 仕様を使用しているリモートクライアント。	USE_STREAMABLE_HTTP=true

Streamable HTTP は POST /mcp、GET /mcp、DELETE /mcp を実行し、MCP-Session-Id ヘッダーでセッションを管理します。/healthz エンドポイントは、アクティブなセッション数が HEALTHZ_MAX_SESSIONS を超えると 503 を返します。これは Kubernetes のライブネスプローブとレディネスプローブ向けです。

---

認証

認証モードは 2 種類あります。適切なモードは、HTTP トランスポートにネットワーク経由でアクセスできるかどうかによって異なります。

接続ごとの OAuth（AUTH_MODE=oauth。ネットワークに公開するデプロイメントでのデフォルト）。サーバーは固定トークンを保持しません。各 MCP 接続は独自の Authorization: Bearer <token> を送信し、サーバーはその接続で有効な PAT として GitLab に転送します。IdP を扱うゲートウェイの背後で実行してください。これにより、チーム全体で 1 つの共有デプロイメントを運用できます。バインドが非ループバックの場合は必須です。

PAT モード（AUTH_MODE=pat。ループバックのみ）。サーバーは GITLAB_PERSONAL_ACCESS_TOKEN に 1 つの個人アクセストークンを保持します。このモードでは、HTTP トランスポートは認証なしで実行されるため、サーバーはループバックのみのバインド（HOST=127.0.0.1）を強制し、それ以外では起動を拒否します。stdio クライアントと単一テナントのローカル開発に適したモードです。Helm ではサポートされていません。チャートの認証検証ガードを参照してください。

---

Configuration

変数	デフォルト	用途
GITLAB_PERSONAL_ACCESS_TOKEN	—	PAT モードでは必須です。
GITLAB_API_URL	https://gitlab.com/api/v4	GitLab API のベース URL です。必要に応じて、セルフホストインスタンスを指定してください。
GITLAB_READ_ONLY_MODE	false	すべての書き込みツールを非表示にします。
AUTH_MODE	pat	pat（ループバックのみ）または oauth（任意のバインド）。
HOST	127.0.0.1	HTTP トランスポートのバインドアドレスです。ネットワークに公開するには 0.0.0.0 を設定します。ただし、AUTH_MODE=oauth の場合に限ります。それ以外の場合、起動は拒否されます。
USE_SSE	false	レガシー SSE トランスポートを有効にします。
USE_STREAMABLE_HTTP	false	MCP Streamable HTTP トランスポートを有効にします。
PORT	3000	SSE および Streamable HTTP 用の HTTP リッスンポートです。
CORS_ALLOW_ORIGINS	(空)	カンマ区切りの許可リストです。空の場合、PAT ループバックモードでは * を意味します（ローカル開発専用）。OAuth モードで空の場合は拒否を意味します。ループバック以外へのバインドでは、ワイルドカードは出力されません。
HEALTHZ_MAX_SESSIONS	10000	このしきい値を超えると、/healthz は 503 を返します。

ローカル開発用に、リポジトリには .env.example が含まれています。

---

デプロイ

Docker

ghcr.io/yoda-digital/mcp-gitlab-server:latest

node:24-alpine を使用したマルチステージビルドです。root 以外（uid 1000）で実行され、すべてのケイパビリティが削除されます。読み取り専用のルートファイルシステム、および Kubernetes の Pod セキュリティ設定 seccompProfile: RuntimeDefault に対応しています。イメージタグはリリース時に semver に従い、latest は最新のタグ付きリリースを指します。

Kubernetes（Helm）

helm install gitlab-mcp oci://ghcr.io/yoda-digital/charts/gitlab-mcp

チャートはデフォルトで AUTH_MODE=oauth に設定されるため、標準のインストールでは認証が必須です。接続ごとに Authorization: Bearer <token> を挿入する Ingress またはゲートウェイを Service の前段に配置してください。

チャートには、/healthz に対するライブネスおよびレディネスプローブ、オプションの PodDisruptionBudget、ローリング再起動用のアノテーション付き ConfigMap と Secret、および不正な設定のレンダリングを拒否する、エラーを明示する5つのガードが含まれています。

• ループバック以外の HOST と AUTH_MODE=pat の組み合わせ（CWE-306 — chart/templates/auth-validation.yaml を参照）
• existingSecret が設定されていない PAT モードでの空の PAT
• existingSecret とインラインの secret.GITLAB_PERSONAL_ACCESS_TOKEN の両方が設定されている（設定しない場合、優先順位が暗黙になるため）
• PDB minAvailable >= replicaCount（ドレイン時のデッドロック）
• PDB で minAvailable と maxUnavailable の両方が設定されている（Kubernetes はアドミッション時にこの組み合わせを拒否します）

values.yaml には helm-docs 用の注釈が付いており、chart/README.md は再生成され、CI で差分がチェックされます。

---

セキュリティ

脆弱性は公開 Issue ではなく、GitHub の非公開脆弱性報告を通じて報告してください。脅威モデルと対象範囲については、SECURITY.md を参照してください。

サプライチェーンに関する事実をいくつか紹介します。すべての npm 公開は、OIDC Trusted Publishing を介した Sigstore provenance で署名されます。CodeQL はすべての push と PR で security-extended および security-and-quality クエリパックを使用して実行されます。Dependabot は有効化され、グループ化され、毎週実行されます。現在のリリースで npm audit が報告する脆弱性はゼロです。main では PR、ステータスチェック、squash または rebase によるマージ、および直線的な履歴が必須です。

読み取り専用モードはリクエスト境界ではなく、ツール登録時に適用されます。回帰によって GITLAB_READ_ONLY_MODE=true の状態で書き込みツールが実行される場合、それはセキュリティ上のバグです。報告してください。

---

エコシステムにおける位置づけ

GitLab と MCP を組み合わせる方法はいくつかあります。状況に合ったものを選んでください。

• GitLab 独自の組み込み MCP サーバー（https://<your-instance>/api/v4/mcp）。15 個のツールを備え、GitLab Premium または Ultimate が必要です。OAuth は GitLab IdP と統合されています。サブスクリプションを利用でき、エージェントにとって 15 個のツールで十分な場合に適しています。
• zereight/gitlab-mcp。コミュニティによる最大規模の実装です。認証方式（PAT、OAuth2 ブラウザーフロー、OAuth プロキシ、リモート認可）が幅広く、ツールもより多く備えています。最大限のカバー範囲を求め、内容を把握する対象が大きくなっても構わない場合に適しています。
• mcpland/gitlab-mcp。ポリシーエンジンに重点を置いています。OAuth2 PKCE、複数インスタンスへのルーティング、Cookie ベースの認証に対応しています。厳密に管理されたエンタープライズ環境に適しています。
• このサーバー（@yoda.digital/gitlab-mcp-server）。86 個のツール、3 種類のトランスポート、PAT と OAuth、Sigstore で来歴が検証された npm リリース、非 root のマルチステージ Docker イメージ、フェイルラウドガードを備えた Helm チャートを提供します。規模が比較的小さく、セキュリティ面で成熟したプロジェクトを Kubernetes 環境にスムーズに導入したい場合に適しています。

どれもあらゆる状況で最適というわけではありません。そうであるかのように装うつもりもありません。

---

コントリビューション

PR を歓迎します。以下の形式でお願いします。

1. フォークし、ブランチを作成します（feature/*、fix/*、docs/*、refactor/*）。
2. Conventional Commits（feat:、fix:、docs:、chore:、…）を使用します。これらが変更履歴の生成に使われます。
3. 動作変更には、vitest のテストを追加または更新します。npm test が必須のチェックです。
4. PR を作成します。CI では build-and-test、CodeQL、Dockerfile の lint、Helm の lint とテンプレートのスモークテスト、Helm チャートの README の差分チェックが実行されます。

ローカル環境のセットアップ：

git clone https://github.com/yoda-digital/mcp-gitlab-server.git
cd mcp-gitlab-server
npm install
npm test
npm run dev

詳しいガイドラインは CONTRIBUTING.md にあります。AI を利用したコントリビューションのルールは ai_code_of_conduct.md にあります。行動規範：CODE_OF_CONDUCT.md。issue トラッカーには、good first issue のチケットもいくつかあります。

---

コントリビューター

このプロジェクトには、その起源から想像される以上に多くの作者がいます。

Ion (Nalyk) Calmîș は最初の作者であり、メンテナーです。Yoda Digital の CTO です。

Olivier Gintrand (@ecthelion77) は、接続ごとの OAuth 認証経路、MCP Streamable HTTP トランスポート、マルチステージ Dockerfile、フェイルラウドガードを含む Helm チャートを作成しました。リリース 0.4.0 と 0.5.0 は主に彼の成果で、PR #42 と PR #44 を通じてマージされました。

Thomas Léveil (@thomasleveil) と BenSchoweCONPORT は、初期の PR を送ってくれました。

Dependabot は変更履歴にある chore コミットの大半を担当しており、決して眠りません。

PR またはセキュリティ報告を送ったのにこの一覧に載っていない場合、それは不具合です。issue を作成してください。

---

ライセンス

MIT。

---

リンク

• npm パッケージ
• Yoda Digital のオープンソースポータル
• 変更履歴
• 運用ガイド
• Cursor の統合
• セキュリティポリシー
• 行動規範
• MCP 仕様

---

Yoda.Digital が ❤️ を込めて開発