MCP Gitlab

🚀 MCP GitLab Server

Model Context Protocol (MCP) サーバーで、包括的なGitLab API統合を提供します。このサーバーにより、LLMはGitLabリポジトリとやり取りし、マージリクエストやイシューを管理し、さまざまなGit操作を実行できます。

🚀 クイックスタート

このMCP GitLabサーバーは、GitLab APIとの包括的な統合を提供し、LLMがGitLabリポジトリとのやり取りを可能にします。以下のセクションでは、インストール方法、設定、使用例、利用可能なツールなどについて説明します。

✨ 主な機能

コア機能

• 🔐 認証とユーザー - 現在のユーザー情報を取得し、ユーザープロファイルを検索します。
• 🔍 プロジェクト管理 - GitLabプロジェクトを一覧表示、検索、詳細を取得します。
• 📝 イシュー - イシューを一覧表示、閲覧、検索、コメントします。
• 🔀 マージリクエスト - マージリクエストを一覧表示、閲覧、更新、承認、マージします。
• 📁 リポジトリファイル - ファイルを閲覧、読み取り、変更をコミットします。
• 🌳 ブランチとタグ - ブランチとタグを一覧表示、管理します。
• 🔧 CI/CDパイプライン - パイプラインのステータス、ジョブ、アーティファクトを表示します。
• 💬 ディスカッション - マージリクエストのディスカッションを読み取り、解決します。
• 🎯 スマート操作 - バッチ操作、AI要約、スマート差分を提供します。

高度な機能

• バッチ操作 - ロールバック機能を備えた複数のGitLab操作を原子的に実行します。
• AI最適化要約 - マージリクエスト、イシュー、パイプラインの簡潔な要約を生成します。
• スマート差分 - 構造化された差分を取得し、コンテキストとサイズ制限を設定できます。
• 安全なプレビュー - コミットする前にファイルの変更をプレビューします。
• 相互参照サポート - バッチモードで前の操作の結果を参照できます。

📦 インストール

uvxを使用する（推奨 - インストール不要）

# インストールせずに直接実行
uvx mcp-gitlab

ソースからインストール

# リポジトリをクローン
git clone https://github.com/Vijay-Duke/mcp-gitlab.git
cd mcp-gitlab

# 依存関係をインストールし、uvで実行
uv sync
uv run mcp-gitlab

# または、テスト依存関係を含む開発モードでインストール
uv sync --all-extras
uv run pytest  # テストを実行する場合

📚 ドキュメント

環境変数

以下の認証トークンのいずれかを設定します。

# プライベートトークン（個人使用を推奨）
export GITLAB_PRIVATE_TOKEN="your-private-token"

# OAuthトークン
export GITLAB_OAUTH_TOKEN="your-oauth-token"

# GitLab URL（オプション、デフォルトはhttps://gitlab.com）
export GITLAB_URL="https://gitlab.example.com"

GitLabトークンの取得方法

1. GitLabのプロファイル設定にアクセスします。
2. 「アクセストークン」に移動します。
3. 以下のスコープを持つ新しいトークンを作成します。
   • api - 完全なAPIアクセス
   • read_repository - リポジトリコンテンツの読み取り
   • write_repository - リポジトリコンテンツの書き込み（コミット用）

💻 使用例

Claude Desktopでの使用

Claude Desktopの設定に追加します。

uvxを使用する場合（推奨 - インストール不要）

{
  "mcp-gitlab": {
    "command": "uvx",
    "args": ["mcp-gitlab"],
    "env": {
      "GITLAB_PRIVATE_TOKEN": "your-token-here"
    }
  }
}

uvを使用する場合（リポジトリをクローンした場合）

{
  "mcp-gitlab": {
    "command": "uv",
    "args": ["run", "mcp-gitlab"],
    "cwd": "/path/to/mcp-gitlab",
    "env": {
      "GITLAB_PRIVATE_TOKEN": "your-token-here"
    }
  }
}

/path/to/mcp-gitlab をリポジトリをクローンしたパスに置き換えてください。

uvxでの実行

MCP GitLabサーバーを実行する最も簡単な方法は、uvx を使用することです。

# GitLabトークンを設定
export GITLAB_PRIVATE_TOKEN="your-token-here"

# uvxでサーバーを直接実行
uvx mcp-gitlab

単独での使用

# ソースから実行する場合（uv syncの後）
uv run mcp-gitlab

# または、Pythonモジュールを直接実行
uv run python -m mcp_gitlab

基本的な使用法

# まず、gitリポジトリから現在のプロジェクトを取得
project = await session.call_tool("gitlab_get_current_project")

# 次に、オープンなイシューを一覧表示
issues = await session.call_tool("gitlab_list_issues", {
    "state": "opened"
})

高度な使用法

# 原子的に：イシューを取得 → ブランチを作成 → 修正をコミット → マージリクエストを作成
result = await session.call_tool("gitlab_batch_operations", {
    "operations": [
        {
            "name": "issue",
            "tool": "gitlab_get_issue", 
            "arguments": {"issue_iid": 123}
        },
        {
            "name": "fix",
            "tool": "gitlab_create_commit",
            "arguments": {
                "branch": "fix-issue-{{issue.iid}}",
                "commit_message": "Fix: {{issue.title}}",
                "actions": [{
                    "action": "update",
                    "file_path": "src/bug.py",
                    "content": "# Fixed code here"
                }]
            }
        },
        {
            "name": "mr",
            "tool": "gitlab_create_merge_request",
            "arguments": {
                "source_branch": "fix-issue-{{issue.iid}}",
                "target_branch": "main",
                "title": "Fix: {{issue.title}}",
                "description": "Fixes #{{issue.iid}}"
            }
        }
    ]
})

🔧 技術詳細

開発のクイックスタート

# 開発用の依存関係をインストール
make install-dev

# すべてのチェックをローカルで実行
make ci-local

# コードをフォーマット
make format

# カバレッジ付きでテストを実行
make test-cov

CI/CDパイプライン

このプロジェクトは、GitHub Actionsを使用して継続的インテグレーションとデプロイを行っています。

• CIパイプライン：すべてのプッシュとPRで実行されます。

  • リンティング（Ruff、Black、isort、MyPy）
  • テスト（pytest with coverage）
  • セキュリティスキャン（Bandit、Safety、pip-audit）
  • 複数バージョンのPythonテスト（3.10、3.11、3.12）

• コード品質：

  • SonarCloud分析
  • CodeQLセキュリティ分析
  • 複雑度メトリクス（Radon、Xenon）

• リリースパイプライン：バージョンタグで自動的にリリースされます。

  • PyPIパッケージの公開
  • Dockerイメージのビルドと公開
  • GitHubリリースの作成

テストの実行

# すべてのテストを実行
uv run pytest tests/ -v

# カバレッジ付きで実行
uv run pytest tests/ --cov=mcp_gitlab

# 特定のテストファイルを実行
uv run pytest tests/test_gitlab_client.py -v

コードスタイル

このプロジェクトでは、以下のツールを使用してコードスタイルを管理しています。

• Black：コードのフォーマット
• isort：インポートのソート
• flake8：リンティング
• mypy：型チェック

# コードをフォーマット
black src/ tests/
isort src/ tests/

# リンターを実行
flake8 src/ tests/
mypy src/

トラブルシューティング

認証問題

• トークンが必要なスコープ（api、read_repository、write_repository）を持っていることを確認してください。
• トークンの有効期限を確認してください。
• セルフホストのインスタンスを使用している場合は、GitLab URLを確認してください。

レート制限

GitLab APIにはレート制限があります。サーバーはレート制限エラーを適切に処理し、適切なエラーメッセージを返します。

大きなレスポンス

レスポンスがサイズ制限を超える場合、自動的に切り捨てられます。ページネーションパラメータを使用して、データをチャンクで取得してください。

📄 ライセンス

このプロジェクトは、Apache License 2.0の下でライセンスされています。詳細については、LICENSE ファイルを参照してください。

謝辞

• Model Context Protocol をベースに構築されています。
• GitLab APIとのやり取りに python-gitlab を使用しています。
• より良いLLM-GitLab統合の必要性に触発されています。