--- title: "GitLab MCPサーバーの接続設定：Claude Code・Cursorでの使い方とツール一覧【2026年11月】" url: "https://www.issoh.co.jp/tech/details/19635/" published: 2026-11-12 updated: 2026-11-12 categories: ["開発"] publisher: "株式会社一創" --- # GitLab MCPサーバーの接続設定：Claude Code・Cursorでの使い方とツール一覧【2026年11月】 GitLab MCPサーバーは、GitLabが公式に提供するMCP（Model Context Protocol）サーバーです。Claude CodeやCursorなどのAIツールから、マージリクエストの読み書き、パイプラインのログ確認、Issueの作成をGitLabのAPI経由で行えます。本記事では、エンドポイント`/api/v4/mcp`への接続手順をクライアント別に示し、OAuthとfine-grained PATの認証、toolsetによるツールの絞り込み、403や429が出たときの切り分け、書き込み操作を許す判断基準までを公式ドキュメントへのリンクつきで解説します。版や仕様は2026年11月12日時点の公式情報です。 ## まとめ：GitLab MCPは/api/v4/mcpへHTTP接続しOAuthで認可 GitLab MCPサーバーはGitLab 19.5で一般提供（GA）になり、Free・Premium・Ultimateのすべてのプランで使えます。GitLab.comでもSelf-Managedでも、接続先は`https:///api/v4/mcp`の1か所です。 Claude Codeなら`claude mcp add`の1コマンドで登録し、ブラウザでOAuthを承認すれば使い始められます。HTTPトランスポートに対応していないクライアントは、`mcp-remote`を挟んで接続します。 つながらないときは、まずトップレベルグループ（Self-Managedではインスタンス）でMCPサーバーへのアクセスが許可されているかと、トークンの種類を確認します。従来型の個人アクセストークンは`mcp`スコープを持てないため、`api`スコープがあっても403で拒否されます。 MRのマージやコミットなど書き込み系のツールも既定で有効なので、信頼できない本文を読ませるならtoolsetを絞ってから運用します。 ## GitLab MCPサーバーとは：19.5でGAの公式サーバーと使える条件 ### 公式サーバーとOSS実装、GitLab DuoのMCPクライアントの違い 「GitLab MCP」で検索すると、名前の似た3種類が混ざって出てきます。混同すると、設定方法もトークンの種類も変わるので、最初に切り分けます。 | 名前 | 接続の向き | 提供元 | 認証 | | ------------------- | ----------------------- | -------------- | ---------------------- | | GitLab MCPサーバー（本記事） | 外部のAIツール → GitLab | GitLab公式・本体に内蔵 | OAuthかfine-grained PAT | | OSSのGitLab向けMCPサーバー | 外部のAIツール → GitLab | 個人・企業の開発者 | 多くは従来型PATを環境変数で渡す | | GitLab MCPクライアント | GitLab Duo → 外部のMCPサーバー | GitLab公式 | 接続先のMCPサーバーによる | 公式サーバーはGitLab本体に組み込まれているため、npmパッケージやDockerイメージを別に入れる必要がありません。逆向きの[GitLab MCPクライアント](https://docs.gitlab.com/user/gitlab%5Fduo/model%5Fcontext%5Fprotocol/mcp%5Fclients/)は、GitLab DuoのAgentic Chatが`.gitlab/duo/mcp.json`に書いた外部ツールを呼ぶ機能です。Duo側のエージェントやフロー、料金の仕組みは[GitLab Duo Agent Platformの機能とGitLab Creditsの見積もり](https://www.issoh.co.jp/tech/details/10660/)で扱っています。MCPという規格そのものの仕組みは[MCP（Model Context Protocol）の仕組みとAPIとの違い](https://www.issoh.co.jp/tech/details/5736/)が入口です。 ### Freeを含む全プランとSelf-Managedで使える条件と18.3からの経緯 [GitLab MCP serverの公式ドキュメント](https://docs.gitlab.com/user/model%5Fcontext%5Fprotocol/mcp%5Fserver/)によると、対象はFree・Premium・Ultimateの全プランで、提供形態もGitLab.com・Self-Managed・Dedicatedのすべてです。版ごとの変化は次のとおりです。 - 18.3：実験的機能として導入 - 18.6：ベータに移行 - 19.2：Freeプランでも使えるように変更 - 19.5：GAに移行し、toolsetの選択機能を追加 - 19.6：`orbit` toolsetを追加 Self-Managedで使うなら、少なくとも19.5以上に上げてから導入するのが無難です。19.4以前はベータ扱いで、前提条件を満たしていないときの応答も403ではなく404でした。19.2でFreeへ広がった背景は[GitLab 19.2で変わったDuo CLIとカスタムフロー](https://www.issoh.co.jp/tech/details/15769/)にまとめています。 ### トップレベルグループのAllow connection to GitLabを確認する手順 MCPサーバーを使う前提は「MCPサーバーへのアクセスが許可されていること」です。GitLab.comではトップレベルグループ単位、Self-ManagedとDedicatedではインスタンス単位で設定します。[グループのアクセス設定のドキュメント](https://docs.gitlab.com/user/group/access%5Fand%5Fpermissions/#allow-access-to-the-mcp-server)にあるGitLab.comでの確認手順は次のとおりで、操作にはトップレベルグループのOwnerロールが要ります。 1. 画面上部の検索欄からトップレベルグループを開く 2. 左サイドバーで「Settings」→「General」を選ぶ 3. 「Permissions and group features」を展開する 4. 「MCP client access」の「Allow connection to GitLab」にチェックが入っているか確かめる 5. 変更したら「Save changes」を選ぶ 19.6以降、Ownerが無効にしていないグループではこの設定が有効です。過去に無効化したグループでは所属する全員が使えません。Self-Managedでは管理者エリアの可視性とアクセス制御の画面に「Allow access to the MCP server」があります。 ## Claude Code・Cursor・CodexからGitLab MCPへつなぐ手順 ### Claude Codeでclaude mcp addを実行しOAuthを承認する手順 Claude CodeはHTTPトランスポートに対応しているので、追加の依存パッケージなしで接続できます。GitLab.comなら`gitlab.com`、Self-Managedなら自社GitLabのホスト名に置き換えて実行します。 ``` # ユーザー全体（-s user）に GitLab MCP サーバーを登録する claude mcp add -s user --transport http GitLab https://gitlab.com/api/v4/mcp # 読み取り中心の toolset に絞って登録する場合 claude mcp add -s user --transport http GitLab https://gitlab.com/api/v4/mcp \ --header "X-Gitlab-Enabled-Mcp-Server-Toolsets: core,work_items" # Claude Code を起動し、チャットで /mcp を入力 → GitLab を選んでブラウザで承認する claude ``` 承認画面はGitLabのOAuth認可ページで、ログイン中のユーザーの権限でアクセスが許可されます。エージェントが触れられるのは、そのユーザーが画面上で操作できるプロジェクトの範囲までです。 ### Cursor・VS Code・CodexにHTTPトランスポートで登録する設定例 CursorはSettingsの「Tools & MCP」→「New MCP Server」で開く`mcp.json`に、次のように書きます。保存するとブラウザが開き、OAuthの承認に進みます。 ``` { "mcpServers": { "GitLab": { "type": "http", "url": "https://gitlab.com/api/v4/mcp", "headers": { "X-Gitlab-Enabled-Mcp-Server-Toolsets": "core,merge_requests,ci" } } } } ``` VS CodeのGitHub Copilotでは、コマンドパレットで「MCP: Add Server」を実行し、種類にHTTP、URLに同じエンドポイント、サーバーIDに`GitLab`を指定します。OpenAI Codexは、公式ドキュメントでは次の3ステップです。 ``` # 1. サーバーを登録する codex mcp add GitLab --url "https://gitlab.com/api/v4/mcp" # 2. ~/.codex/config.toml に次の内容があることを確かめる # [features] # "rmcp_client" = true # # [mcp_servers.GitLab] # url = "https://gitlab.com/api/v4/mcp" # 3. ブラウザで OAuth を承認する codex mcp login GitLab ``` Gemini CLI、Kiro、Zedなども接続先URLは同じで、違うのは設定の書き場所だけです。 ### Claude DesktopなどHTTP非対応のクライアントはmcp-remoteで接続 設定ファイルにURLを直接書けないクライアントでは、ローカルで`mcp-remote`を起動し、stdioとHTTPを中継させます。Node.js 20以降が必要です。Claude Desktopなら「Settings」→「Developer」→「Edit Config」で次を追加し、アプリを再起動します。 ``` { "mcpServers": { "GitLab": { "command": "npx", "args": [ "-y", "mcp-remote", "https://gitlab.com/api/v4/mcp", "--header", "X-Gitlab-Enabled-Mcp-Server-Toolsets: core,merge_requests" ] } } } ``` 初回の接続時にブラウザが開き、OAuthを承認するとトークンが`~/.mcp-auth/`に保存されます。HTTPトランスポートとstdioの違い、SSEからの移行の経緯は[MCPのトランスポートStreamable HTTPとSSEの違い](https://www.issoh.co.jp/tech/details/6580/)で解説しています。 ### OAuthのDCRとfine-grained PAT、従来型PATが403になる理由 GitLab MCPサーバーが受け付けるトークンは2種類だけです。1つは`mcp`スコープを持つOAuthアクセストークンで、クライアントが動的クライアント登録（DCR）でOAuthアプリケーションを自動作成するか、事前に登録したアプリケーションを使って取得します。もう1つは、[fine-grained PATの権限一覧](https://docs.gitlab.com/auth/tokens/fine%5Fgrained%5Faccess%5Ftokens%5Frest/)にある「MCP tool」リソースへ「Execute」権限を付けた個人アクセストークンです。 従来型の個人・プロジェクト・グループアクセストークンは`mcp`スコープを付けられず、`api`スコープがあっても`403 Forbidden`（`insufficient_scope`）になります。OSSのMCPサーバー向けのPATを流用して詰まる原因はこれです。 OAuthの事前登録は[GitLabのOAuthプロバイダ設定](https://docs.gitlab.com/integration/oauth%5Fprovider/)で行い、スコープに`mcp`を選び、「Confidential」のチェックを外して作成します。DCRに代わる登録方式の動向は[MCPでDCRに代わるCIMDの仕組み](https://www.issoh.co.jp/tech/details/10011/)も参考になります。 ## GitLab MCPのツール一覧とtoolsetヘッダーで操作範囲を絞る設定 ### 既定で有効な6つのtoolsetと読み取り・書き込みツールの区別 [MCP serverのツールリファレンス](https://docs.gitlab.com/user/model%5Fcontext%5Fprotocol/mcp%5Fserver%5Ftools/)では、ツールがtoolsetという単位にまとめられています。既定で有効なものと、書き込みにあたる代表的なツールは次のとおりです。 | toolset | 既定 | 読めるもの | 代表的な書き込みツール | | -------------------- | -------- | ------------ | ---------------------- | | meta | 常に有効 | サーバーの版 | なし | | core | 有効 | プロジェクト・検索結果 | save\_note（コメント） | | merge\_requests | 有効 | MRの差分・コメント | accept\_merge\_request | | work\_items | 有効 | Issueなどの作業項目 | save\_work\_item | | repository | 有効 | ファイル・コミット | add\_commit | | ci | 有効 | パイプライン・ジョブログ | save\_pipeline | | duo\_agent\_platform | Duo利用時のみ | Duoセッションの状態 | start\_duo\_session | このほか`wikis`、`code_security`（脆弱性の参照・更新、Ultimate）、`orbit`はオプトインです。既定のままだと、エージェントはMRのマージやコミットまで実行できます。 旧ツールの`create_issue`と`get_pipeline_jobs`は非表示扱いで、後継は`save_work_item`と`get_pipeline`です。 ### toolsetヘッダーでMRのマージとコミットの道具を外す設定例 使うtoolsetは、リクエストヘッダー`X-Gitlab-Enabled-Mcp-Server-Toolsets`にカンマ区切りで指定します。ヘッダーを省くと既定の6つ、`all`を指定するとオプトイン分も含めた全toolsetが有効になります。 ``` { "mcpServers": { "GitLab-readonly": { "type": "http", "url": "https://gitlab.example.com/api/v4/mcp", "headers": { "X-Gitlab-Enabled-Mcp-Server-Toolsets": "core,ci", "X-Gitlab-Mcp-Server-Tool-Name-Prefix": "gl_" } } } } ``` 注意点は、toolset単位の指定なので「読み取りツールだけ」には分けられないことです。`core`には`save_note`（コメント投稿）が、`ci`には`save_pipeline`（パイプラインの実行・キャンセル）が含まれます。ここで`merge_requests`と`repository`を外すと、マージとコミットの道具はエージェントから見えなくなります。 2つ目のヘッダーはツール名の接頭辞です。GitHubのMCPサーバーと同時につなぐと`search`のような同名ツールが並ぶため、`gl_search`のように区別させます。 ### MRの要約とパイプライン失敗の原因調査をエージェントに頼む指示例 接続できたら、エージェントにはURLかプロジェクトのパスと番号を渡して頼みます。`get_merge_request`はMRのURLだけでも、`project_id`と`merge_request_iid`の組でも対象を特定できます。 ``` # MR の確認（get_merge_request が diff・コミット・コメントをまとめて取得する） https://gitlab.com/example-group/web-app/-/merge_requests/128 の変更点を要約し、 テストが追加されていないファイルを挙げてください。コメントはまだ投稿しないでください。 # パイプライン失敗の調査（get_pipeline と get_job でジョブのログを読む） example-group/web-app の main ブランチで直近に失敗したパイプラインを探し、 失敗したジョブのログから原因の行を抜き出してください。 ``` 「投稿しないでください」のように書き込みの可否を指示に含めても、ツール自体は呼べる状態のままです。確実に止めたいなら、前のh3のとおりtoolsetから外します。 ## 403・429・プロトコル不一致などGitLab MCPの接続エラーの対処 ### 403のdenial\_reasonで判別するグループ設定とトークン種別の誤り [MCP serverのトラブルシューティング](https://docs.gitlab.com/user/model%5Fcontext%5Fprotocol/mcp%5Fserver%5Ftroubleshooting/)に載っている主なエラーを、原因の切り分け順に並べると次のとおりです。 | 症状 | 原因 | 対処 | | -------------------------- | ---------------- | ---------------------- | | 403・no\_enabled\_namespace | どのグループもMCPを未許可 | グループのOwnerに設定を依頼 | | 403（Self-Managed） | インスタンス設定が無効 | 管理者に設定を依頼 | | 403・insufficient\_scope | mcpスコープのないトークン | OAuthかfine-grained PAT | | protocol version エラー | 仕様の版の不一致（18.6以前） | クライアントかGitLabを更新 | | 429 Too Many Requests | MCPまたはAPIのレート制限 | Retry-Afterの秒数待って再試行 | 403はまずレスポンス本文の`denial_reason`を確認してください。グループ側の未許可なら`no_enabled_namespace`、インスタンス設定の無効なら`instance_setting_disabled`が入り、トークン種別の誤りは`insufficient_scope`エラーとして返ります。Self-Managedなら管理者が`mcp.log`で同じ値を確認できます。`mcp-remote`経由で認証の状態がおかしいときは、`~/.mcp-auth/mcp-remote*`を削除してから接続し直すのが公式の手順です。対応する仕様の版は`2025-11-25`・`2025-06-18`・`2025-03-26`で、[MCP仕様の2025-11-25版](https://modelcontextprotocol.io/specification/2025-11-25)が現行の基準になっています。 ### GitLab.comのプラン別レート制限とDCRの1時間10件制限への備え GitLab.comのMCPサーバーには、ユーザー単位のレート制限があります。クライアントやトークンを分けても合算されます。 | プラン | 1分あたり | 1時間あたり | | -------- | ----- | ------ | | Free | 60 | 3,600 | | Premium | 600 | 5,000 | | Ultimate | 600 | 5,000 | エージェントに大量のMRを横断して調べさせると、Freeの毎分60回には数分で届きます。ツールが呼ぶAPI側（検索など）の制限に当たった場合はHTTP 200のまま`rate_limited`というツール結果が返るので、自作のクライアントではメッセージ文字列ではなく`error.type`で判定します。 もう1つの落とし穴はDCRです。動的クライアント登録はIPアドレスごとに1時間10件まで。社内プロキシで出口IPを共有していると、全員が一斉に接続した日に承認で失敗する人が出ます。対策は、管理者かグループOwnerが`mcp`スコープのOAuthアプリケーションを登録し、その`clientId`を配る運用です。リダイレクトURIが違うクライアントは共有できないので、種類ごとに作ります。 ## GitLab MCPの導入判断：任せてよい操作と書き込みを止める場面 ### 採用が向くのはMRとCIの調査を毎日エージェントに頼むチーム 導入効果がはっきり出るのは、MRの差分やジョブログをブラウザで行き来して読んでいる作業です。`get_job`はログと成果物まで取れるので、エディタの中で「失敗したジョブの原因を探して直す」までが完結します。 Claude CodeやCursorを既に入れているチームなら、OSSのGitLab向けMCPサーバーを新たに選ぶ理由はほぼありません。公式版は追加のサーバー運用が要らず、OAuthでユーザー本人の権限に閉じ、ツール呼び出しごとの監査イベントも記録できます。GitLabの基本操作から確認したい場合は[GitLabのプロジェクト作成からMR・CI/CDまでの手順](https://www.issoh.co.jp/tech/details/18874/)、GitHubの公式MCPと比べたい場合は[GitHub MCPサーバーのtoolsetと権限設定](https://www.issoh.co.jp/tech/details/6209/)が対になる記事です。 ### プロンプトインジェクション対策なしで書き込みを許可しない判断基準 公式ドキュメントは、MCPツールを使うときのプロンプトインジェクション対策を利用者の責任と明記しています。エージェントはIssueやMRの本文を読み、その内容に従って次のツールを呼ぶため、本文に仕込まれた指示でマージやコミットを実行させられる経路があります。 次のどれかに当てはまる環境では、`merge_requests`と`repository`のtoolsetを外し、読み取り中心の構成で運用してください。 - 社外の人がIssueやMRを作れる公開プロジェクトにアクセスできるユーザーで接続している - Maintainer以上の権限を持つアカウントで、保護ブランチへのマージが可能な状態になっている - クライアント側でツール呼び出しを毎回承認する設定を切り、自動実行にしている いちばん危ないのは2つ目と3つ目の組み合わせです。エージェント専用に権限を絞ったアカウントを用意し、保護ブランチの承認ルールで人のレビューを必須にすれば、仮に指示を仕込まれても本番ブランチまでは届きません。この権限設計やCI/CDの承認フローを社内で組む人手がない場合は、一創の[DevOps・CI/CD導入支援](https://www.issoh.co.jp/service/system/devops/)のように、開発基盤の設計と運用ルールづくりを外部に任せる方法もあります。 ## よくある質問 GitLab MCPについて調べている方から多い質問に、2026年11月時点の公式情報をもとに回答します。 ### GitLab MCPサーバーは無料で使えますか？ 使えます。GitLab 19.2でFreeプランへ提供範囲が広がり、19.5でGAになりました。GitLab.comのFreeプランでは1分60回・1時間3,600回のレート制限がかかります。なお`duo_agent_platform` toolsetからGitLab Duoのセッションを起動する場合は、Duo Agent Platform側の利用条件と課金（GitLab Credits）に従います。 ### GitHub MCPサーバーとの違いは何ですか？ 役割は同じで、AIツールからリポジトリやMR（GitHubではPR）、CIを操作するための公式サーバーです。GitHubはリモート版とローカル版の2つを提供していますが、GitLabは本体に内蔵された1つで、Self-Managedでも自社のGitLabがそのままMCPサーバーになります。ツールの絞り込みはどちらもtoolset単位です。GitHub側の詳細は[GitHub Remote MCP Serverの接続手順](https://www.issoh.co.jp/tech/details/7271/)で扱っています。 ### セルフホストのGitLabでも使えますか？ Self-ManagedとDedicatedでも使えます。管理者がインスタンス全体で「Allow access to the MCP server」を有効にし、クライアントには`https://自社のホスト/api/v4/mcp`を指定します。レート制限は既定で無効で、上限値は管理者が決める仕組みです。19.4以前はベータ扱いのため、19.5以上への更新を先に済ませてください。 ### 個人アクセストークンで接続できますか？ fine-grained PATなら接続できます。「MCP tool」リソースに「Execute」権限を付けて発行してください。従来型の個人アクセストークンは`mcp`スコープを持てないため、`api`スコープを付けていても403になります。OAuthに対応したクライアントなら、ブラウザで承認する方式のほうがトークンの管理が要らず手間が少なく済みます。 ### GitLab Duoを契約していなくてもMCPサーバーは使えますか？ 使えます。MCPサーバー自体はDuoの契約と関係なく、Freeを含む全プランで利用可能です。Duo Agent Platformが使えない環境では`duo_agent_platform` toolsetが出てこないだけで、MR・Issue・リポジトリ・CIの各ツールは動きます。Duoの機能と費用の見積もり方は[GitLab Duo Agent Platformの解説](https://www.issoh.co.jp/tech/details/10660/)を参照してください。 ## 関連記事 - [GitLab Duo Agent Platformとは？料金（GitLab Credits）の見積もりとフロー13本・安全設定【2026年11月】](https://www.issoh.co.jp/tech/details/10660/)：GitLab側のAIエージェントとMCPクライアントの機能・料金を確認できます - [GitLabとは：構成要素・CEとEEの違い・3つの提供形態とDockerで試す手順【2026年11月】](https://www.issoh.co.jp/tech/details/19631/)：MCPサーバーを内蔵するGitLab本体の構成と提供形態を整理できます - [GitHub MCPサーバーとは？できること・22のtoolset・導入手順と権限設定を解説【2026年10月】](https://www.issoh.co.jp/tech/details/6209/)：GitHub側の公式MCPサーバーのtoolsetと比べられます - [MCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方](https://www.issoh.co.jp/tech/details/5736/)：MCPの仕組みから理解したいときの入口です - [GitHubとGitLabの違い｜ActionsとGitLab CIの対応表・料金・セルフホスト比較](https://www.issoh.co.jp/tech/details/4219/)：GitHubとGitLabのどちらを使うかを決める比較です --- 出典: [GitLab MCPサーバーの接続設定：Claude Code・Cursorでの使い方とツール一覧【2026年11月】]()（株式会社一創）