mcp-gitlab-server

mcp-gitlab-server

⚠️ 開発段階に関する注意
このプロジェクトは現在、開発段階です。機能や API は予告なく変更される場合があります。本番環境での使用にはご注意ください。

python-gitlab をベースにした GitLab MCP サーバーです。

インストール

Personal Access Token を使用する場合（最も一般的）

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_TOKEN": "<your GitLab personal access token>",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

OAuth2 Token を使用する場合

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_OAUTH_TOKEN": "<your GitLab OAuth2 token>",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

セルフホストの GitLab インスタンスでは、GITLAB_URL に GitLab インスタンスの URL（例：https://gitlab.example.com）を設定してください。設定しない場合、デフォルトで https://gitlab.com が使用されます。

認証

この MCP サーバーは、2 種類の認証方法に対応しています。

方法 1：Personal Access Token（ほとんどのユーザーに推奨）

1. GitLab Personal Access Token を作成します。

   • GitLab → User Settings → Access Tokens に移動します
   • read_api スコープ（最低限必要）を指定してトークンを作成します

2. GITLAB_TOKEN 環境変数にトークンの値を設定します

方法 2：OAuth2 Token（OAuth2 アプリケーション向け）

1. GitLab OAuth2 アプリケーションのフローで取得した OAuth2 トークンがある場合
2. GITLAB_OAUTH_TOKEN 環境変数に OAuth2 トークンの値を設定します

OAuth2 アプリケーションを作成するには：

1. GitLab → User Settings → Applications に移動します
2. 適切なスコープ（最低限 read_api）を指定して、新しいアプリケーションを作成します
3. OAuth2 フローを使用してアクセストークンを取得します
4. そのトークンを GITLAB_OAUTH_TOKEN として使用します

環境変数

• GITLAB_TOKEN - GitLab Personal Access Token（Personal Access Token 認証を使用する場合）
• GITLAB_OAUTH_TOKEN - GitLab OAuth2 Token（OAuth2 認証を使用する場合）
• GITLAB_URL - GitLab インスタンスの URL（デフォルトは https://gitlab.com）

注： サーバーはまず GITLAB_OAUTH_TOKEN を確認し、見つからない場合は GITLAB_TOKEN を使用します。設定が必要なのは、いずれか一方のみです。

ツール

リポジトリとプロジェクトの管理

• list_projects - 認証済みユーザーがアクセスできる GitLab プロジェクトを一覧表示します（所有・スター付きによるフィルタリングとページネーションに対応）
• list_groups - 認証済みユーザーがアクセスできる GitLab グループを一覧表示します
• list_group_projects - 指定した GitLab グループ内のすべてのプロジェクトを一覧表示します
• get_user_info - 認証済みユーザーの情報を取得します
• search_repositories - 名前、説明、キーワードで GitLab リポジトリを検索します
• get_repository_details - 指定したリポジトリの詳細情報を取得します

コードへのアクセス

• read_repository_code - フィルタリングオプションを指定して、リポジトリのコード構造と内容をすべて読み取ります
• read_repository_file - リポジトリ内の指定したファイルの内容を読み取ります

マージリクエスト分析

• list_merge_requests - 状態、並べ替え、ページネーションでフィルタリングして、リポジトリのマージリクエストを一覧表示します
• get_merge_request_analytics - 作成からマージまでの平均時間を含む、マージリクエストの期間に関する包括的な統計を算出します

リポジトリコードの読み取り機能

この MCP サーバーは、強力なコード読み取り機能を提供します。

read_repository_code

高度なフィルタリングを使用して、リポジトリ構造全体とファイルの内容を読み取ります。

• 選択的な読み取り：glob パターンを使用してファイルの包含・除外を指定します（例：*.py,*.js、または *.log,node_modules/* を除外）
• サイズ制限：読み込むファイルの最大数とファイルサイズの上限を設定し、応答が過大になるのを防ぎます
• ブランチ／タグへの対応：任意のブランチ、タグ、コミット SHA から読み取ります
• ディレクトリによるフィルタリング：リポジトリ内の特定のディレクトリに絞り込みます
• スマートフィルタリング：一般的なビルド成果物、ログ、バイナリファイルを自動的に除外します

使用例：

• Python ファイルのみを読み取る：include_patterns: "*.py"
• テストを除外する：exclude_patterns: "*test*,*spec*"
• 特定のディレクトリを読み取る：path: "src/"
• 別のブランチを指定する：ref: "develop"

read_repository_file

リポジトリ内の個別ファイルを読み取ります。

• 単一ファイルへのアクセス：特定のファイルの内容をすばやく取得します
• メタデータを含む：ファイルサイズ、エンコーディング、最終コミット情報が含まれます
• バイナリの検出：バイナリファイルを安全に処理します
• 柔軟な参照：ブランチ、タグ、コミット SHA に対応します

制限と安全性：

• デフォルト：最大 50 ファイル、1 ファイルあたり 100KB
• タイムアウトを防ぐため、制限を設定できます
• バイナリファイルを自動検出します
• 大規模なリポジトリでも適切にエラーを処理します

マージリクエストの分析機能

MCP サーバーは、包括的なマージリクエスト分析機能を提供します。

list_merge_requests

高度なフィルタリングと並べ替えを使用して、マージリクエストを一覧表示します。

• 状態によるフィルタリング：状態（opened、closed、merged、all）で絞り込みます
• 柔軟な並べ替え：作成日、更新日、タイトルの順に並べ替えます
• 豊富なメタデータ：作成者、担当者、レビュアー、ラベル、投票情報が含まれます
• ページネーションに対応：返される結果数を指定できます

get_merge_request_analytics

マージリクエストの詳細な存続期間統計を算出します。

• 存続期間の分析：作成からマージまでの平均、中央値、最小／最大時間
• 統計分布：25、75、90 パーセンタイルの分析
• 期間の指定：過去 N 日間（デフォルト：90 日）の MR を分析します
• 詳細な内訳：正確な存続期間を算出した個々の MR の詳細
• 複数の時間単位：時間と日数の両方で結果を表示します

回答できる質問の例：

• 「acapulco リポジトリの MR の平均存続期間はどのくらいですか？」
• 「マージリクエストは通常、マージされるまでにどのくらいかかりますか？」
• 「マージリクエストの存続期間はどのように分布していますか？」
• 「マージに最も時間がかかったマージリクエストはどれですか？」

分析結果：

• マージ所要時間の平均、中央値、最小値、最大値
• パーセンタイル分析（25、75、90 パーセンタイル）
• 個々の存続期間を含むサンプルのマージリクエスト
• さらなる分析に使用できる完全なデータセット

開発

# Clone the repository
git clone <repo-url>
cd gitlab-mcp-server

# Install dependencies
uv sync

# Run in development mode
uv run python -m mcp_gitlab_server

テストの設定

開発およびテストでは、ローカルの wheel ファイルをインストールして使用できます。

テスト用の MCP 設定：

{
  "mcpServers": {
    "GitLab": {
      "command": "uvx",
      "args": [
        "--from", "/path/to/your/gitlab-mcp-server/dist/mcp_gitlab_server-0.1.0-py3-none-any.whl",
        "gitlab-mcp-server"
      ],
      "env": {
        "GITLAB_TOKEN": "your-gitlab-token-here",
        "GITLAB_URL": "https://gitlab.com"
      }
    }
  }
}

ビルドとテストの手順：

# Build the wheel file
uv build

# Test with MCP client (like Claude Desktop)
# Update your MCP configuration with the local wheel path
# The wheel file will be in ./dist/ directory

# For quick testing, verify the server starts:
uv run python -m mcp_gitlab_server