GitLab MCP

GitLab MCP は、ハーネス非依存のModel Context Protocolサーバーであり、GitLabリポジトリ作業のための共有Agent Skillsを備えています。Codex、Claude Code、Cline、Piは、それぞれ別のGitLab実装ではなく、同じ正規MCPコアのサポート対象ディストリビューションです。ChatGPTは、リモートのStreamable HTTPデプロイを通じて同じコアを利用できます。

このプロジェクトが提供するもの:

• 型付きツールを備えた自己完結型のGitLab MCPサーバー

• 汎用の$gitlabスキル;

• 未解決のマージリクエストディスカッションのための$gl-address-comments;

• パイプラインおよびジョブ診断のための$gl-fix-ci;

• ブランチ、コミット、プッシュ、下書きMRの配信のための$gl-publish;

• GitLabネイティブのランナー、CI lint、ガバナンス、タグ、リリース、パイプラインスケジュールのワークフローに加え、シークレットセーフなプロジェクトおよびグループのCI/CD変数管理;

• 同じ正規コアとエージェントスキルを再利用する軽量のCodex、Claude Code、Cline、Piディストリビューション; および

• ChatGPTデプロイのためのステートレスなTransmit Transport HTTPトランスポートとOAuth保護リソースメタデータ。

はじめに

ドキュメントインデックスは、ユーザー、オペレーター、開発者、セキュリティ、互換性、およびリリースに関する全ドキュメントセットへのリンクをまとめています。

Related MCP server: GitLab MCP Server

クイックスタート

ローカルソースインストールの場合は、Node.js 22以降を使用し、正規のMCPコアのビルドと検証を行います。

npm.cmd ci
npm.cmd test
npm.cmd run build

ハーネスに一致したものを選択してください。サポートされている4種類のアダプターはすべて、同じビルド済みMCPバンドルとサニティーン系エージェントスキルを利用します。

Codexの場合は、このリポジトリを信頼できるローカルマーケットプレイスに追加し、gitlabプラグインをインストールして、Codexを再起動または更新します。確立されたルートのCodexマニフェスト、.mcp.json、プリロード、アーティファクト名は、サポートされる互換性のあるインターフェースのままです。Codexを起動する環境でGitLabインスタンスとトークンを設定します。

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

新しい会話を開始し、Codexに接続を確認するよう依頼します。例:

Use GitLab to tell me which account and instance are connected.

Claude Codeユーザーは、同じMCPサーバーと正規のAgentスキルを同梱する、具体化されたネイティブプラグインディストリビューションを読み込めます。パッケージの検証、--plugin-dirでの読み込み、マーケットプレイス対応レイアウトについては、 Claude Codeアダプターガイドを参照してください。

Clineユーザーは、stdio組み込みで同じ正規MCPバンドルを使用し、別のGitLab実装を必要とせずにデフォルトのAgentスキルをインストールできます。IDEおよびCLIのセットアップについては、Clineアダプターガイドを参照してください。

Piユーザーは、専用のPiパッケージをインストールできます。これは、シンプルなstdioブリッジを介して正規MCPツール群を登録し、同じAgentスキルを提供します。パッケージのインストール、実行時の依存関係の処理、ブリッジの制限については、Piアダプターガイドを参照してください。

一般的なGitLabワークフロー、最小権限トークンのガイダンス、ChatGPT HTTPデプロイについては、(docs/USER_GUIDE.md)を参照してください。

要件

• Node.js 22以降

• GitLab.com、GitLab Dedicated、またはセルフマネージドGitLabインスタンス

• ローカルのstdioで使用する場合、実行する操作に必要な最小限のスコープを持つGitLabトークン

ビルドと検証

npm.cmd install
npm.cmd test
npm.cmd run adapters:check
npm.cmd run check:bundle
npm.cmd run build
npm.cmd run validate:codex
npm.cmd run validate:claude
npm.cmd run validate:cline
npm.cmd run validate:pi
npm.cmd run check:versions
npm.cmd run check:gitlab-oauth -- https://gitlab.example.com

正規のMCPバンドルドルパスはdistribution.jsonで定義されます。現在の構成ではserver/dist/gitlab-mcp.cjsが生成されます。MCPバンドル自体は、ソースソースコントロールでは無視され、生成後にリリースアーティファクトに含まれます。ハーネスパッケージは、ハーネスごとの追加のランタイム依存関係を宣言することができます。Piパッケージは、例えば、MCP SDKを介してPiをそのバンドルサーバーにブリッジします。

distribution.jsonは、共有ディストリビューション識別子、ベースバージョン、説明、ライセンス、正規MCPバンドル、Skillsパスなど、共有配布メタデータの信頼できる情報源です。これを変更したら、npm run adapters:generateを実行して、生成されたCodex/Claude Code/Cline/Piメタデータを確認します。npm run adapters:checkは、メタデータのドリフト、正規Skillsパスが存在しない、ディレクトリでない、またはリポジトリ外、などを検出して拒否します。

npm run check:bundleはメモリ内のクリーンビルドを実行し、正規のバンドルにハーネス固有の実装参照が含まれている場合に失敗します。npm run check:versionsは、生成されたパッケージとCodexのリリースメタデータがdistribution.jsonに一致していることを検証します。Codexプラグインマニフェストは、+の後にCodexビルドメタデータを追加することができますが、そのベースのディストリビューションのバージョンは変更されません。**SERVER_VERSIONは独立して所有され、ハーネスに依存しないMCPコアによって管理されており、コアランタイム自体が変更された場合にのみ増分されます。

ハーネス非依存コアとアダプターの境界は、 ADR-001に文書化されています。GEN-08の集中的な監査とアイデンティティに関する決定は、 docs/GENERALISATION_AUDIT.mdに記録されています。

継続的インテグレーション

GitLabのマージ(nuance)前、シーサイドジョブなど)、デフォルトブランチ、タグのパイプラインでは、構文チェック、テスト、カバレッジ、依存クルーザー、フォーマット/リンク、プロダクション依存ライブラリの監査、クリーンなバンドルビルド、バンドルされたstdio/HTTPスモークテストが実行されます。GitLab SASTおよびシークレット検出テンプレートも有効です。Codex、Claude Code、Cline、Piにはそれぞれ、正規ビルド後に焦点を当てたアダプター検証があります。これらのジョブは、ハーネスのパッケージングとMCP起動を検証しますが、コアのNode/セキュリティマトリクスは成功しません。

タグのパイプラインではさらに、決定論的なCodexアーカイブとそのCycloneDX SBOM およびSHA256SUMS に加え、対応する.sha256サイドカーを備えた再現可能なClaude Code、Cline、Pi MCP + Skillsアーカイブを、GitLabジョブアーティファクトとして公開します。最終のリリースセットゲートは、正確に4つのサポート対象ハーネスのみを許可し、それらの正規MCPバンドルとスキルのダイジェストを比較します。リリースは、アーティファクトがdocs/PUBLICATION_CHECKLIST.mdに従って検証されるまで完了とは見なされません。

コミット済みのdocs/gitlab-tool-contracts.jsonインベントリは、登録されたすべてのツールを境界値の入力で呼び出し、その安全分類、HTTPメソッド、エンコードされたルート、クエリ/ボディマッピング、および制限付きレスポンスモードをロックします。カバレッジはすべてのプロダクションソースモジュールをカバーし、90%の行、80%の関数、または75%のブランチを下回ると失敗します。インベントリエントリなしでツールを追加するとテストが失敗します。

構文テストとテストジョブはnode:22-alpineとnode:24-alpineの両方で実行されます。閾値が適用されたカバレッジジョブはNode 22で実行されます。コアジョブは、これらのイメージを実行でき、npmレジストリに到達できるタグなしのLinuxランナーを必要とします。セキュリティテンプレートは、アナライザーイメージをGitLabレジストリから取得します。コアのNode.jsジョブに特権モードは必要ありません。少なくとも1つのプロジェクト、グループ、またはインスタンスランナーを設定して、タグなしジョブを受け入れ、マージに成功できる実行パイプラインを要求する前に、ジョブを最低10分間実行できるようにします。

ローカルCodex認証

Codexを起動する環境でインスタンスURLとトークンを設定します。

$env:GITLAB_URL = "https://gitlab.example.com"
$env:GITLAB_TOKEN = "<token>"

GITLAB_URLはデフォルトでHTTPSを使用しなければならず、埋め込まれた認証情報、クエリ、フラグメントを拒否します。TLSを使用できない明示的なローカル/プライベート開発GitLabインスタンスの場合は、GITLAB_ALLOW_INSECURE_HTTP=trueを設定します。このオーバーライドは本番環境とパブリックホスト名では拒否されます。ループバック、プライベートネットワークIP、単一ラベルのホスト、およびプライベート開発用サフィックス.localhost、.local、.internal、.home.arpaを受け入れます。

GITLAB_URLのデフォルト値はhttps://gitlab.comです。Codexの.mcp.jsonは、バンドルされたサーバーをstdioで起動し、ハーネス非依存のコアの前に薄いCodexディストリビューションアダプターをロードします。トークンは実行時に読み取られ、ディストリビューションに保存されることはありません。

タスクをカバーする最小限のトークンスコープを使用してください。読み取り専用の作業には読み取りを行いトークンを使用できます。リポジトリ、issues、マージリクエスト、CIの変更には、対応するGitLab API権限が必要です。

機能の検出

GitLab機能がサポートされていない、ライセンスがない、無効、または現在の認証情報だけではアクセスできないかどうかを診断する前に、get_gitlab_capabilitiesを呼び出してください。これは/user、/version、/metadata、/personal_access_tokens/self、および(認証情報が個人アクセストークンでない場合) /oauth/token/infoへの読み取り専用リクエストのみを使用します。OAuth診断はスコープと残り時間を報告しますが、トークンやOAuthアプリケーション識別子を公開することはありません。GitLabは、特に古いセルフマネージドバージョンや非管理者の場合、これらのエンドポイントを隠したり省略したりすることがあるため、あいまいな結果は推測ではなくunknownとして報告されます。

各機能は、available、unavailable、 permission_required、license_required、not_configured、またはunknownのいずれでもあり、簡潔な理由と、必要に応じてそれを裏付けする情報が含まれます。正規化されたプローブごとの結果を得るにはdetailed: trueを、キャッシュをバイパスするにはrefresh: trueを渡してください。

結果は、正規化されたインスタンスURLと認証された資格情報ごとに60秒間キャッシュされます。キャッシュキーには生のベアラートークンではなく、単方向SHA-256ダイジェストが含まれます。エントリは60秒後に失効し、refreshによってバイパスされ、インスタンスや変更された資格情報を自然に分離します。期限切れのエントリは必要に応じて削除され、LRUの上限によりハードメモリ境界が提供されます。キャッシュはインメモリのみで、プロセスが再起動するとクリア再されます。

HTTPサーバー

ローカル開発環境の場合:

$env:MCP_PUBLIC_URL = "https://mcp.example.com/mcp"
$env:GITLAB_URL = "https://gitlab.example.com"
npm.cmd run start:http

HTTPモードでは、すべての/mcpリクエストにベアラートークンが必要です。サーバー側のトークンはデフォルトで無効です。ALLOW_SERVER_TOKEN_HTTP=trueは、管理されたプライベートテストのみに存在し、共有デプロイには使用しないでください。

検査専用デプロイとしてMCP_READ_ONLY=trueを設定します。このモードでは、サーバーは読み取り専用で注釈されたツールのみを登録し、GitLabのread_api OAuthスコープを広告します。デフォルトの書き込み要求モードは完全なツールセットとapiを必要とします。サーバーは登録時にすべてのツールの注釈を検証するため、未分類または変更を行うツールが読み取り専用の表面に静かに入り込むことはできません。

IPv4ワイルドカード0.0.0.0またはIPv6ワイルドカード::にバインドする場合は、MCP_ALLOWED_HOSTSをカンマ区切りの公開ホスト名の許可リストに設定します。サービスをHTTPSの背後に置き、MCP_PUBLIC_URLをその正規の公開/mcpURLに設定します。本番モードではMCP_PUBLIC_URLが必須となり、埋め込み認証情報、クエリ、フラグメント、および/mcp以外のパスを拒否し、HTTPSを要求します。MCP_ALLOW_INSECURE_PUBLIC_URL=trueは、ループバックリスナー上での明示的なローカル開発専用であり、本番環境または公開ホストでは拒否されます。ALLOW_SERVER_TOKEN_HTTP=trueも同様にループバックのプライベートテストに限定されており、共有デプロイメントには使用しないでください。

インストールまたはデプロイ後に、読み取り専用のget_runtime_infoツールを使用して、コア/ディストリビューションのバージョン、デプロイメントモード、読み取り専用フィルタリング、および登録済みツールインベントリの決定論的SHA-256フィンガープリントを確認します。

HTTP MCPリクエスト本文は、デフォルトで8 MiBに制限されています。これにより、境界のある複数ファイルコミットやその他の正当な大きなツールペイロードに対応しつつ、無制限のリクエストバッファリングを防ぎます。MCP_MAX_REQUEST_BYTESを65,536〜26,214,400バイトの整数に設定すると、別のデプロイメント制限を使用できます。サーバーの前にあるリバースプロキシは、少なくとも同じリクエストサイズを許可する必要があります。

長時間実行されるHTTPデプロイメントでは、認証とリクエスト状態も制限されます。

• MCP_TOKEN_CACHE_MAX_ENTRIESは、検証済みベアラーIDを制限し、デフォルト256、TTL 60秒、LRU退避付き。

• MCP_AUTH_FAILURE_LIMITは、MCP_AUTH_FAILURE_WINDOW_MS内の直接接続アドレスごとの拒否トークンを制限し、デフォルトは60秒あたり20回の失敗。

• MCP_AUTH_FAILURE_MAX_ENTRIESは、失敗追跡状態を制限し、デフォルト1,024。

• MCP_MAX_CONCURRENT_REQUESTSは、アクティブなMCPリクエストを制限し、デフォルト32。

• MCP_MAX_CONCURRENT_REQUESTS_PER_IDENTITYは、検証済みのGitLabユーザー1人あたりのリクエストを制限し、デフォルト4。

TLSリバースプロキシで、補完的なレート制限と接続制限を構成します。アプリケーションは、デフォルトでは転送ヘッダーを信頼せず、意図的に直接のピアアドレスを使用するため、トラフィックがこのサービスに到達する前に、プロキシレベルでクライアントIP制限を適用する必要があります。

認証されていない/healthエンドポイントは、トポロジーに依存しないプロセスの死活確認です。/readyは別の準備完了チェックであり、依存関係プローブが利用できない場合は503を返します。すべてのレスポンスには、生成されたX-Request-Idが含まれます。内部MCP障害は、その識別子とエラータイプのみをログに記録します。埋め込み側は、ベアラートークンやリクエストペイロードを受信せずに、メトリクス用のリクエスト完了オブザーバーを提供できます。

デプロイ後、公開リソースのメタデータと両方のヘルスセマンティクスを確認します。

npm.cmd run check:mcp-deployment -- https://mcp.example.com/mcp

セキュリティモデル

• ツールは、読み取り専用、書き込み、破壊的な注釈をアドバタイズします。

• create_commitは、非破壊的なファイル操作のみをサポートします。削除および強制コミット更新には、同時実行安全性フィールドを持つ個別に注釈が付けられたcreate_destructive_commitツールが必要です。

• GitLabのレスポンス本文（ジョブログ、アーティファクト、APIエラーを含む）は、厳格なバイト制限の下でストリーミングされ、リクエストタイムアウトの対象となります。

• APIエラーは、認証情報をエコーせずに正規化されます。

• 機能検出は、エラー証拠を編集し、プライベートCI変数や変更エンドポイントを読み取ることはありません。

• HTTPベアラートークンは、構成されたGitLabインスタンスに対して検証され、境界のあるTTL/LRUキャッシュ内の一方向トークンハッシュによってキャッシュされます。

• 拒否された認証情報と同時リクエストは、トークンやプライベートIDの詳細をログに記録せずに制限されます。

• HTTPモードは、保護されたリソースメタデータを使用して未認証リクエストにチャレンジします。

• HTTPツールは、ツールごとのOAuthまたはプライベートサーバートークンセキュリティスキームに加えて、モデルから見える再認証チャレンジをアドバタイズします。

• スキルには、マージ、承認、削除、ディスカッションの解決、CI状態の変更に明示的な意図が必要です。

ライセンス

MIT