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として自動的に公開されます。

• 呼び出しごとのプロジェクトスコープ — すべてのツールは、プロジェクトをまたいだクエリのために GITLAB_PROJECT_PATH を上書きするオプションの project_path を受け入れます。

• ページネーション — リストツールは、page、total、has_more、next_page を含む pagination ブロックと、Markdownフッターの次ページヒントを返します。

• MCPコンテキスト統合 — gitlab_pipeline_health と gitlab_get_job_log は async であり、MCPコンテキストを通じて info ログや report_progress イベントを発行するため、クライアントはプログレスバーを表示できます。

• MCPリソース — gitlab://project/info と gitlab://project/ci-config は、ツールよりもリソースモデルを好むクライアントのために一般的な検索をミラーリングします。

• ライフサイクル管理 — python-gitlab のHTTPセッションは、asynccontextmanager ライフサイクル・フックを介してサーバー終了時にクリーンに閉じられます。

• ログのgrep — gitlab_get_job_log は grep_pattern + grep_context（周辺行）を受け入れ、メガバイト規模のCIログ全体をエージェントのコンテキストに取り込むことなく、正規表現でフィルタリングできます。

スレッドモデル

FastMCPは同期ツールを自動的にワーカー・スレッド（anyio.to_thread.run_sync）で実行するため、asyncioイベントループをブロックしません。python-gitlab は同期ライブラリであり、すべての呼び出しを自分で asyncio.to_thread でラップするのは手間がかかるためです。MCPコンテキスト（進捗、情報ログ）を活用するツールは 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 дней（過去7日間のmasterの健全性を表示して）。

インストール

Python 3.10+が必要です。

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

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

設定

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

すべてのツールは、呼び出しごとに GITLAB_PROJECT_PATH を上書きするオプションの 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

同様に、MCP設定で上記の環境変数を指定して uvx --from gitlab-ci-mcp gitlab-ci-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で1時間あたり2000リクエスト。管理者が設定可能 — インスタンスの /admin/application_settings/network を参照）。

• サーバーは project_path ごとに 1つの python-gitlab HTTPセッションをキャッシュするため、同じプロジェクトに対する繰り返しのツール呼び出しは接続を再利用し、毎回再認証することはありません。

• リストツールはデフォルトで per_page=20 となっており、1回の呼び出しを少数のAPIリクエスト内に収めます。

• 429 Too Many Requests に達した場合、エラーハンドラーがアクション可能なメッセージを返します。待機してから、より大きな per_page または少ない呼び出し回数で再試行してください。

企業プロキシの背後にあるセルフホストGitLab

ラップトップにローカル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メッセージをstdinで待機）：

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

ライセンス

MIT — LICENSE を参照。

謝辞

python-gitlab および MCP Python SDK を基に構築されています。