開発

GitLab MCPサーバーの接続設定：Claude Code・Cursorでの使い方とツール一覧【2026年11月】

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://<GitLabのホスト>/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クライアントは、GitLab DuoのAgentic Chatが.gitlab/duo/mcp.jsonに書いた外部ツールを呼ぶ機能です。Duo側のエージェントやフロー、料金の仕組みはGitLab Duo Agent Platformの機能とGitLab Creditsの見積もりで扱っています。MCPという規格そのものの仕組みはMCP（Model Context Protocol）の仕組みとAPIとの違いが入口です。

Freeを含む全プランとSelf-Managedで使える条件と18.3からの経緯

GitLab MCP serverの公式ドキュメントによると、対象は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とカスタムフローにまとめています。

トップレベルグループのAllow connection to GitLabを確認する手順

MCPサーバーを使う前提は「MCPサーバーへのアクセスが許可されていること」です。GitLab.comではトップレベルグループ単位、Self-ManagedとDedicatedではインスタンス単位で設定します。グループのアクセス設定のドキュメントにある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の違いで解説しています。

OAuthのDCRとfine-grained PAT、従来型PATが403になる理由

GitLab MCPサーバーが受け付けるトークンは2種類だけです。1つはmcpスコープを持つOAuthアクセストークンで、クライアントが動的クライアント登録（DCR）でOAuthアプリケーションを自動作成するか、事前に登録したアプリケーションを使って取得します。もう1つは、fine-grained PATの権限一覧にある「MCP tool」リソースへ「Execute」権限を付けた個人アクセストークンです。

従来型の個人・プロジェクト・グループアクセストークンはmcpスコープを付けられず、apiスコープがあっても403 Forbidden（insufficient_scope）になります。OSSのMCPサーバー向けのPATを流用して詰まる原因はこれです。

OAuthの事前登録はGitLabのOAuthプロバイダ設定で行い、スコープにmcpを選び、「Confidential」のチェックを外して作成します。DCRに代わる登録方式の動向はMCPでDCRに代わるCIMDの仕組みも参考になります。

GitLab MCPのツール一覧とtoolsetヘッダーで操作範囲を絞る設定

既定で有効な6つのtoolsetと読み取り・書き込みツールの区別

MCP serverのツールリファレンスでは、ツールが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のトラブルシューティングに載っている主なエラーを、原因の切り分け順に並べると次のとおりです。

症状 原因 対処
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版が現行の基準になっています。

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までの手順、GitHubの公式MCPと比べたい場合はGitHub MCPサーバーのtoolsetと権限設定が対になる記事です。

プロンプトインジェクション対策なしで書き込みを許可しない判断基準

公式ドキュメントは、MCPツールを使うときのプロンプトインジェクション対策を利用者の責任と明記しています。エージェントはIssueやMRの本文を読み、その内容に従って次のツールを呼ぶため、本文に仕込まれた指示でマージやコミットを実行させられる経路があります。

次のどれかに当てはまる環境では、merge_requestsとrepositoryのtoolsetを外し、読み取り中心の構成で運用してください。

  • 社外の人がIssueやMRを作れる公開プロジェクトにアクセスできるユーザーで接続している
  • Maintainer以上の権限を持つアカウントで、保護ブランチへのマージが可能な状態になっている
  • クライアント側でツール呼び出しを毎回承認する設定を切り、自動実行にしている

いちばん危ないのは2つ目と3つ目の組み合わせです。エージェント専用に権限を絞ったアカウントを用意し、保護ブランチの承認ルールで人のレビューを必須にすれば、仮に指示を仕込まれても本番ブランチまでは届きません。この権限設計やCI/CDの承認フローを社内で組む人手がない場合は、一創のDevOps・CI/CD導入支援のように、開発基盤の設計と運用ルールづくりを外部に任せる方法もあります。

よくある質問

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の接続手順で扱っています。

セルフホストの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の解説を参照してください。

関連記事

お気に入りに入れた記事の一覧

一創の公式 SNS

X では毎朝の新着記事と IT ニュースの速報を、YouTube・TikTok・Instagram・LinkedIn・Facebook では記事の解説動画を配信しています。

この記事は以下の記事からリンクされています

この記事に関連するサービス

資料請求

今日のトレンド記事 直近 24 時間で、いつもより多く読まれている記事

  1. 2026.01.21　コラム 税務調査の録音は禁止？判例・裁決と国税局マニュアルで見る、断られたときの対応
  2. 2026.11.09　テックブログ エディオン不正アクセス第2報：カード番号の対象確認とログ・決済画面の改ざん対策
  3. 2026.11.11　テックブログ Microsoft 2026年11月の月例更新：Outlookの悪用済みCVE-2026-124194と修正版の確認方法
  4. 2026.11.11　テックブログ JANISの不正アクセス：最大11,652名の医療機関情報と情報窃取プログラムの検知設定
  5. 2026.11.11　テックブログ SMBC日興証券の不正アクセス：持株会会員最大5.6万人の範囲と受託システムの分離設計

RELATED POSTS 関連記事

一覧へ戻る

目次