MCP Gitlab

MCP GitLab CrunchTools

GitLab プロジェクト、マージリクエスト、イシュー、パイプライン、検索に対応する安全な MCP（Model Context Protocol）サーバーです。gitlab.com、セルフホスト環境、エンタープライズ環境など、あらゆる GitLab インスタンスで動作します。

概要

この MCP サーバーは、次のように設計されています。

• デフォルトで安全 - 文書化された脅威モデル（SECURITY.md を参照）、Pydantic による入力検証、誤ってログに記録されるのを防ぐための SecretStr としての API トークン保持
• サードパーティサービス不要 - stdio 経由でローカル実行され、API トークンがマシンの外に出ることはありません
• 複数インスタンスに対応 - 設定可能な URL により、gitlab.com、セルフホストの GitLab、エンタープライズインスタンスで動作します
• クロスプラットフォーム - Linux、macOS、Windows で動作します
• 自動更新 - GitHub Actions が CVE を監視し、依存関係を更新します
• コンテナー化 - Hummingbird Python ベースイメージ上に構築され、quay.io/crunchtools/mcp-gitlab で利用できます

命名規則

コンポーネント	名前
GitHub リポジトリ	crunchtools/mcp-gitlab
コンテナー	quay.io/crunchtools/mcp-gitlab
Python パッケージ（PyPI）	mcp-gitlab-crunchtools
CLI コマンド	mcp-gitlab-crunchtools
モジュールインポート	mcp_gitlab_crunchtools

Hummingbird を選ぶ理由

このコンテナーイメージは、Project Hummingbird の Hummingbird Python ベースイメージ上に構築されており、次の特長があります。

• CVE のリスクを最小化 - 最小限のパッケージセットで構築され、攻撃対象領域を大幅に縮小します
• 定期的な更新 - セキュリティパッチが迅速に適用されます
• Python 向けに最適化 - uv パッケージマネージャーを備えた、事前設定済みの Python 環境
• 本番環境に対応 - 適切なシグナル処理と、デフォルトで非 root ユーザーを使用します

機能

プロジェクト管理（5 ツール）

• list_projects - フィルタリングと検索を使用してプロジェクトを一覧表示します
• get_project - ID またはパスでプロジェクトの詳細を取得します
• list_project_branches - リポジトリのブランチを一覧表示します
• get_project_branch - 単一のブランチを取得します
• list_project_commits - 日付やパスでフィルタリングしてコミットを一覧表示します

グループ管理（3 ツール）

• list_groups - フィルタリングしてグループを一覧表示します
• get_group - ID またはパスでグループの詳細を取得します
• list_group_projects - グループ内のプロジェクトを一覧表示します（サブグループに対応）

マージリクエスト（7 ツール）

• list_merge_requests - 状態、ラベル、マイルストーンで MR を一覧表示します
• get_merge_request - MR の詳細を取得します
• create_merge_request - 新しい MR を作成します
• update_merge_request - MR のタイトル、説明、状態、担当者を更新します
• list_mr_notes - MR のコメントを一覧表示します
• create_mr_note - MR にコメントを追加します
• get_mr_changes - MR の差分を取得します

イシュー（6 ツール）

• list_issues - 状態、ラベル、マイルストーン、担当者でイシューを一覧表示します
• get_issue - イシューの詳細を取得します
• create_issue - 新しいイシューを作成します
• update_issue - イシューのタイトル、説明、状態、ラベルを更新します
• list_issue_notes - イシューのコメントを一覧表示します
• create_issue_note - イシューにコメントを追加します

パイプライン（4 ツール）

• list_pipelines - 状態でフィルタリングして CI/CD パイプラインを一覧表示します
• get_pipeline - パイプラインの詳細を取得します
• list_pipeline_jobs - パイプライン内のジョブを一覧表示します
• get_job_log - ジョブログの出力を取得します

検索（2 ツール）

• search_global - アクセス可能なすべての GitLab リソースを検索します
• search_project - 特定のプロジェクト内を検索します

インストール

uvx を使用する場合（推奨）

uvx mcp-gitlab-crunchtools

pip を使用する場合

pip install mcp-gitlab-crunchtools

コンテナーを使用する場合

podman run -e GITLAB_TOKEN=your_token \
    quay.io/crunchtools/mcp-gitlab

設定

環境変数

変数	必須	デフォルト	説明
GITLAB_TOKEN	はい	—	パーソナルアクセストークン
GITLAB_URL	いいえ	https://gitlab.com	GitLab インスタンスの URL
SSL_CERT_FILE	いいえ	—	カスタム CA バンドルのパス。内部 CA を使用するセルフホスト GitLab 向け
GITLAB_SSL_VERIFY	いいえ	true	TLS 検証を無効にするには false を設定します（推奨されません）

GitLab パーソナルアクセストークンの作成

1. アクセストークンに移動

   • https://gitlab.com/-/user_settings/personal_access_tokens に移動します
   • または、アバター > 設定 > アクセストークンを選択します

2. カスタムトークンを作成

   • 名前：mcp-gitlab-crunchtools
   • 有効期限：適切な日付を設定します（90日を推奨）
   • スコープ：必要に応じてスコープを選択します

3. スコープの選択

   スコープ	アクセスレベル	機能
   read_api	読み取り専用	プロジェクト、イシュー、MR、パイプラインの一覧表示と閲覧
   api	フルアクセス	作成・更新を含むすべての機能

4. トークンをコピーして保存

   • トークンをすぐにコピーします（glpat-で始まります）
   • パスワードマネージャーに安全に保存します

Claude Code に追加

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- uvx mcp-gitlab-crunchtools

セルフホスト型 GitLab の場合：

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    --env GITLAB_URL=https://gitlab.example.com \
    -- uvx mcp-gitlab-crunchtools

コンテナ版の場合：

claude mcp add mcp-gitlab-crunchtools \
    --env GITLAB_TOKEN=your_token_here \
    -- podman run -i --rm -e GITLAB_TOKEN quay.io/crunchtools/mcp-gitlab

使用例

プロジェクト一覧の表示

User: List my GitLab projects
Assistant: [calls list_projects with membership=true]

マージリクエストの表示

User: Show open merge requests for my-org/backend
Assistant: [calls list_merge_requests with project_id="my-org/backend"]

イシューの作成

User: Create an issue in my-org/backend titled "Fix login timeout"
Assistant: [calls create_issue with title="Fix login timeout"]

パイプラインのステータス確認

User: Show failed pipelines for my-org/api
Assistant: [calls list_pipelines with status="failed"]

コードの検索

User: Search for "authentication" in my-org/backend
Assistant: [calls search_project with scope="blobs"]

セキュリティ

このサーバーは、セキュリティを最優先事項として設計されています。詳しくは SECURITY.md をご覧ください。

• 脅威モデルと攻撃ベクトル
• 多層防御アーキテクチャ
• トークン取り扱いのベストプラクティス
• 入力検証ルール
• 監査ログ

主なセキュリティ機能

1. トークン保護

   • SecretStr として保存されます（誤ってログに記録されることはありません）
   • 環境変数のみで管理されます（ファイルや引数には保存されません）
   • すべてのエラーメッセージからサニタイズされます

2. 入力検証

   • すべての入力に Pydantic モデルを使用します
   • プロジェクト ID／グループ ID の文字を許可リストで検証します
   • パストラバーサルを防止します

3. API の強化

   • HTTPS を強制します（localhost を除く）
   • TLS 証明書を検証します
   • リクエストをタイムアウトします（30 秒）
   • レスポンスサイズを制限します（10MB）

4. CVE の自動スキャン

   • GitHub Actions で依存関係を毎週スキャンします
   • Trivy でコンテナのセキュリティをスキャンします
   • Python の CodeQL 分析を実施します

開発

セットアップ

git clone https://github.com/crunchtools/mcp-gitlab.git
cd mcp-gitlab
uv sync

テストの実行

uv run pytest

リントと型チェック

uv run ruff check src tests
uv run mypy src

コンテナのビルド

podman build -t mcp-gitlab .

ライセンス

AGPL-3.0-or-later

貢献

貢献を歓迎します。セキュリティ関連の変更を提出する前に、SECURITY.md をお読みください。

リンク

• GitLab REST API ドキュメント
• FastMCP ドキュメント
• MCP 仕様
• crunchtools.com