GitLab MCP Server注目

GitLab MCP Server とは？

GitLab MCP Server は、AI アシスタントが GitLab API を通じてプロジェクトの検索、ファイルの読み取り、コミットのプッシュ、issue・ブランチ・フォーク・マージリクエストの作成を行えるようにする gitlab mcp 連携です。このページはアーカイブ済みのリファレンス版で、現在は GitLab 公式のメンテナンスされた MCP サーバーがあります。

このページに掲載されているパッケージ @modelcontextprotocol/server-gitlab は、Model Context Protocol プロジェクトが公開したリファレンスサーバーの一つです。現在は servers-archived リポジトリに移されており、同リポジトリは収録サーバーがメンテナンスされておらず、セキュリティ保証もないと明記しています。npm のパッケージもサポート終了と表示されています。新規導入には、GitLab 本体に組み込まれたリモートエンドポイント /api/v4/mcp である公式 GitLab MCP サーバーを使ってください。以下では両方を説明します。

GitLab MCP Server の使い方

公式 GitLab MCP サーバー（推奨）

前提条件：GitLab.com ではトップレベルグループで、GitLab Self-Managed と GitLab Dedicated ではインスタンスで、MCP サーバーへのアクセスを許可しておく必要があります。認証は OAuth です。初回接続時にクライアントが自身を登録し（OAuth 2.0 Dynamic Client Registration）、ブラウザが開くのでリクエストを承認します。MCP ツール権限を持つきめ細かい個人アクセストークンも使えますが、従来型の個人アクセストークン、プロジェクトアクセストークン、グループアクセストークンは使えません。

以下の例では、<gitlab.example.com> を gitlab.com またはセルフホストのインスタンス URL に置き換えてください。

Claude Code

claude mcp add -s user --transport http GitLab https://<gitlab.example.com>/api/v4/mcp

claude を起動して /mcp と入力し、GitLab サーバーを選んでブラウザで認可を承認します。

Claude Desktop

Node.js 20 以降が必要です。claude_desktop_config.json に次を追加し、Claude Desktop を再起動します。

{
  "mcpServers": {
    "GitLab": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://<gitlab.example.com>/api/v4/mcp"]
    }
  }
}

Cursor

Settings > Cursor Settings > Tools & MCP で、mcp.json に新しい MCP サーバーを追加します。

{
  "mcpServers": {
    "GitLab": {
      "type": "http",
      "url": "https://<gitlab.example.com>/api/v4/mcp"
    }
  }
}

VS Code

コマンドパレットを開いて MCP: Add Server を実行し、HTTP を選んで https://<gitlab.example.com>/api/v4/mcp を入力、ID を GitLab にして OAuth リクエストを承認します。

Codex

codex mcp add GitLab --url "https://<gitlab.example.com>/api/v4/mcp"
codex mcp login GitLab

GitLab のドキュメントでは、~/.codex/config.toml の [features] で rmcp_client を有効にするよう案内されています。

アーカイブ済みリファレンスサーバー（このページの設定）

api スコープ（読み取り専用なら read_api）の GitLab 個人アクセストークンを作成し、npx でパッケージを実行します。

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

GITLAB_API_URL は任意で、セルフホストのインスタンスでのみ必要です。README には Docker イメージ mcp/gitlab も記載されています。

GitLab MCP Server の主な機能

• 公式サーバーは GitLab に組み込まれており、GitLab.com、Self-Managed、Dedicated の Free・Premium・Ultimate で利用できます。GitLab 19.5 で一般提供（GA）になりました。
• HTTP クライアントならローカルインストール不要：https://<instance>/api/v4/mcp に接続して OAuth でサインインするだけです。
• core、merge_requests、work_items、repository、ci などのツールグループ（toolsets）を、X-Gitlab-Enabled-Mcp-Server-Toolsets ヘッダーで選択できます。
• X-Gitlab-Mcp-Server-Tool-Name-Prefix ヘッダーでツール名に接頭辞を付けられ、複数の GitLab インスタンスを接続するときに便利です。
• すべてのツール呼び出しで、あなた自身のプロジェクトと名前空間の権限が確認されます。
• アーカイブ版サーバーは、ファイル作成・更新時に存在しないブランチを自動作成し、強制プッシュなしで単一ファイル・複数ファイルのコミットに対応します。

GitLab MCP Server のツール

アーカイブ済みリファレンスサーバーは、このページに表示されている 9 つのツールを提供します。

• リポジトリとファイル： search_repositories、create_repository、fork_repository、create_branch、get_file_contents。
• コミット： create_or_update_file は 1 ファイルを書き込み、push_files は複数ファイルを 1 回のコミットでプッシュします。
• コラボレーション： create_issue と create_merge_request（ドラフト対応）。

公式 GitLab MCP サーバーには、get_merge_request_diffs、save_merge_request_review、list_pipelines、get_job、list_work_items、semantic_search、Ultimate の脆弱性ツールなど、より多くのメンテナンスされたツールがあります。最新の一覧は GitLab の MCP サーバーツールのドキュメントを参照してください。

GitLab MCP Server のユースケース

• コードレビュー：「マージリクエスト !42 の diff を要約し、リスクのある変更を挙げて」
• issue のトリアージ：「my-group/api に 'Login timeout' というタイトルで bug ラベル付きの issue を作成して」
• チャットからの小さな修正：「fix-readme ブランチを作り、README.md を更新してドラフトのマージリクエストを開いて」
• CI のデバッグ（公式サーバー）：「main の最新パイプラインはなぜ失敗した？失敗したジョブのログを見せて」
• コードベースの質問：「develop ブランチの src/config.ts を読んで、デフォルト値を説明して」

GitLab MCP Server と代替ツールの比較

• 公式 GitLab MCP サーバーとこのアーカイブ版パッケージ： 公式版は GitLab がメンテナンスし、長期トークンではなく OAuth を使い、パイプライン、作業アイテム、レビューまでカバーし、HTTP クライアントではローカルプロセスも不要です。アーカイブ版は基本的なリポジトリ、issue、マージリクエスト操作のみです。
• コミュニティ製 GitLab サーバー： GitLab MR MCP などは、マージリクエストと issue に特化しています。
• GitLab ではなく GitHub を使う場合： GitHub MCP Server を使ってください。

GitLab MCP Server のトラブルシューティング

• 公式サーバーで 403 Forbidden（GitLab 19.4 以前では 404 Not Found）：グループやインスタンスで MCP サーバーが許可されていないか、従来型の個人・プロジェクト・グループアクセストークンを使っています。前提条件を確認し、OAuth かきめ細かいトークンを使ってください。
• 429 Too Many Requests： MCP または API のレート制限に達しています。制限がリセットされるまでリクエストは失敗します。
• mcp-remote で OAuth が失敗し続ける： rm -rf ~/.mcp-auth/mcp-remote* でローカルの認証キャッシュを削除して再接続します。
• アーカイブ版サーバーで認証エラー： GITLAB_PERSONAL_ACCESS_TOKEN に api スコープがあるか、セルフホストの場合 GITLAB_API_URL が /api/v4 で終わっているかを確認します。