gitlab-ci-mcp

gitlab-ci-mcp

GitLab CI/CD 用の MCP サーバーです。LLM エージェント（Claude Code、Cursor、OpenCode、DevX Agent など）で、パイプライン、ジョブ、スケジュール、ブランチ、タグ、マージリクエスト、リポジトリファイルを操作できます。

Python、FastMCP、stdio トランスポートを使用します。

GitLab SaaS の gitlab.com と、セルフホスト／オンプレミスのどちらでも動作します。企業ネットワークを考慮して設計されており、NO_PROXY の設定、SSL 検証の切り替え（オプション）、環境変数によるプロジェクト単位のスコープ設定に対応しています。

設計上の特長

• ツールのアノテーション — すべてのツールに readOnlyHint／destructiveHint／idempotentHint／openWorldHint が付与されているため、MCP クライアントは操作を分類できます（たとえば、gitlab_merge_mr や gitlab_delete_schedule のような破壊的な操作に限って確認を求められます）。
• すべてのツールで構造化出力 — 各ツールは TypedDict の戻り値型を宣言するため、FastMCP が outputSchema を自動生成し、すべての結果に、事前にレンダリングされた Markdown テキストブロックとともに structuredContent が含まれます。構造化データをレンダリングできるクライアントはそれを使用し、簡潔なテキストを優先するエージェントは Markdown を使用します。response_format パラメーターは不要です。
• 構造化エラー — 認証エラー、404、403、429（レート制限）、5xx、環境変数の不足は、実行可能な ToolError メッセージ（例：「GitLab 認証に失敗しました……GITLAB_TOKEN に api スコープがあることを確認してください」）に変換され、isError=True の結果として通知されます。
• Pydantic による入力検証 — すべての引数に型付きの制約（範囲、長さ、リテラル）があり、JSON Schema として自動的に公開されます。
• 呼び出しごとのプロジェクトスコープ — すべてのツールで省略可能な project_path を指定でき、クロスプロジェクトのクエリでは GITLAB_PROJECT_PATH を上書きします。
• ページネーション — 一覧表示ツールは page、total、has_more、next_page を含む pagination ブロックと、Markdown のフッターに次のページへのヒントを返します。
• MCP Context との統合 — gitlab_pipeline_health と gitlab_get_job_log は async で、MCP Context を通じて info ログ／report_progress イベントを出力し、クライアントが進捗バーを表示できるようにします。
• MCP リソース — gitlab://project/info と gitlab://project/ci-config は、ツールよりも Resource モデルを優先するクライアント向けに、一般的な情報取得機能を提供します。
• ライフスパン管理 — サーバーのシャットダウン時に、asynccontextmanager ライフスパンフックを通じて python-gitlab の HTTP セッションを適切に終了します。
• ログの grep — gitlab_get_job_log は grep_pattern と grep_context（前後の行）を受け付け、CI ログ全体をエージェントのコンテキストに取り込まずに、メガバイト規模のログを正規表現でフィルタリングできます。

スレッドモデル

FastMCP は同期ツールを自動的にワーカースレッドで実行するため （anyio.to_thread.run_sync）、asyncio イベントループをブロックしません。 python-gitlab は同期ライブラリであり、すべての呼び出しを自分で asyncio.to_thread でラップしても煩雑になるだけです。MCP Context （進捗、info ログ）の恩恵を受けるツールは async def で実装し、 python-gitlab の呼び出しを明示的に asyncio.to_thread でラップします。

機能

日常的な CI/CD 業務をカバーする 23 個のツール：

パイプライン gitlab_list_pipelines · gitlab_get_pipeline · gitlab_get_pipeline_jobs · gitlab_get_job_log · gitlab_trigger_pipeline · gitlab_retry_pipeline · gitlab_cancel_pipeline · gitlab_pipeline_health

スケジュール gitlab_list_schedules · gitlab_create_schedule · gitlab_update_schedule · gitlab_delete_schedule

ブランチとタグ gitlab_list_branches · gitlab_list_tags · gitlab_compare_branches

マージリクエスト gitlab_list_merge_requests · gitlab_get_merge_request · gitlab_get_merge_request_changes · gitlab_create_merge_request · gitlab_merge_mr

リポジトリとプロジェクト gitlab_get_file · gitlab_list_repository_tree · gitlab_project_info

パイプラインのヘルスレポート

gitlab_pipeline_health は、過去 7 日間／30 日間のすぐに読める概要を返します：

Last 7d:  96.4%  up   | 27/28 success
Last 30d: 92.1%       | 105/114 success
Last 10:  success success success failed success ...

オンコール対応やトリアージに便利です：покажи health master за последние 7 дней。

インストール

Python 3.10 以降が必要です。

# via uvx (recommended)
uvx --from gitlab-ci-mcp gitlab-ci-mcp

# or via pip/pipx
pipx install gitlab-ci-mcp

設定

すべての設定は環境変数で行います：

変数	必須	説明
GITLAB_URL	はい	ベース URL。例：https://gitlab.example.com
GITLAB_TOKEN	はい	api スコープを持つパーソナルアクセストークン
GITLAB_PROJECT_PATH	はい	デフォルトのプロジェクト。例：my-org/my-repo
GITLAB_SSL_VERIFY	いいえ	true（デフォルト）／false
GITLAB_NO_PROXY_DOMAINS	いいえ	NO_PROXY に追加するドメインをカンマ区切りで指定します（ローカル HTTP プロキシ経由の社内ネットワークで便利です。例：.corp.example.com,gitlab.internal）

すべてのツールで省略可能な project_path 引数を指定すると、呼び出しごとに GITLAB_PROJECT_PATH を上書きできます。複数プロジェクトにまたがるクエリに便利です。

Claude Code

詳しい手順： docs/claude-code.md — 前提条件、2 通りのインストール方法、複数プロジェクトの設定、社内プロキシ経由のセルフホスト GitLab、トラブルシューティング、アンインストール。

簡単な手順：

claude mcp add gitlab uvx --from gitlab-ci-mcp gitlab-ci-mcp \
  --env GITLAB_URL=https://gitlab.example.com \
  --env GITLAB_TOKEN=glpat-xxxxxx \
  --env GITLAB_PROJECT_PATH=my-org/my-repo

または、~/.claude.json／プロジェクトの .mcp.json に設定します：

{
  "mcpServers": {
    "gitlab": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "gitlab-ci-mcp", "gitlab-ci-mcp"],
      "env": {
        "GITLAB_URL": "https://gitlab.example.com",
        "GITLAB_TOKEN": "${GITLAB_TOKEN}",
        "GITLAB_PROJECT_PATH": "my-org/my-repo",
        "GITLAB_SSL_VERIFY": "true"
      }
    }
  }
}

確認：

claude mcp list
# gitlab: uvx --from gitlab-ci-mcp gitlab-ci-mcp - ✓ Connected

Cursor / OpenCode / DevX Agent

同様に、上記の環境変数とともに uvx --from gitlab-ci-mcp gitlab-ci-mcp を MCP 設定に指定します。各ツール固有の MCP 設定構文を参照してください。

プロンプトの例

что сломалось в последнем pipeline master

покажи health master за 7 дней для проекта my-org/other-repo

создай MR из feature/foo в master с title "feat: foo"

покажи содержимое .gitlab-ci.yml из master

レート制限と接続の再利用

GitLab にはユーザーごとのレート制限があります（REST API では通常 2000 リクエスト／時。管理者が設定できます。インスタンスの /admin/application_settings/network を参照してください）。

• サーバーは python-gitlab の HTTP セッションを project_path ごとに 1 つキャッシュするため、同じプロジェクトへのツール呼び出しを繰り返す際に接続が再利用され、毎回再認証する必要はありません。
• リスト取得ツールのデフォルトは per_page=20 で、1 回の呼び出しに必要な API リクエスト数を少なく抑えます。
• 429 Too Many Requests が発生した場合、エラーハンドラーが対処方法を示すメッセージを返します。しばらく待ってから、per_page を大きくするか、呼び出し回数を減らして再試行してください。

社内プロキシ経由のセルフホスト GitLab

ノート PC でローカル HTTP プロキシ（例：社内 Web アクセス用の http://127.0.0.1:3128）を使っている一方、GitLab がイントラネット上にある場合、プロキシが内部リクエストを傍受して切断することがあります。対処方法は 2 つあります：

1. GITLAB_NO_PROXY_DOMAINS を設定します。サーバーは起動時にドメインを NO_PROXY に追加し、さらに自身のプロセスから HTTP_PROXY／HTTPS_PROXY をクリアして、GitLab との通信に影響しないようにします。
2. MCP の env セクションで HTTP_PROXY="" などを明示的に渡します。

開発

git clone https://github.com/mshegolev/gitlab-ci-mcp
cd gitlab-ci-mcp
python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'
pytest

サーバーを直接実行します（stdio トランスポートを使用し、標準入力から MCP メッセージを待ち受けます）：

GITLAB_URL=... GITLAB_TOKEN=... GITLAB_PROJECT_PATH=... gitlab-ci-mcp

ライセンス

MIT — LICENSE を参照してください。

謝辞

python-gitlab と MCP Python SDK を基盤に構築されています。