gitlab-mcp-server

GitLab MCP サーバー

機能を強化した、GitLab リポジトリと連携するための Model Context Protocol（MCP）サーバーです。

概要

この MCP サーバーを使うと、AI アシスタント（Claude など）が GitLab リポジトリと連携し、プロジェクト、イシュー、マージリクエストなどを管理できます。元の実装を拡張し、エンドポイントを追加するとともに、エラー処理を改善しています。

機能

• プロジェクト管理

  • 新しいリポジトリの作成（グループの名前空間に対応）
  • プロジェクト設定の更新（公開範囲を含む）
  • プロジェクトの削除
  • プロジェクトのフォーク
  • リポジトリの検索

• ファイル操作

  • ファイルの内容の取得
  • ファイルの作成または更新
  • 複数のファイルを一度にコミット

• リポジトリ管理

  • ブランチの作成
  • イシューの作成
  • マージリクエストの作成

• イシューと時間の追跡

  • 絞り込みオプションを指定したイシューの取得
  • イシューの詳細情報の取得
  • 時間の追跡（見積もり時間と作業時間）の管理
  • 時間追跡の統計情報の表示
  • イシュー属性の更新
  • イシューのクローズと再オープン

• ノート（コメント）

  • イシューのコメントの取得
  • コメントの新規作成
  • 既存のコメントの更新
  • コメントの削除

• ラベル管理

  • プロジェクトのラベルの取得
  • ラベルの作成、更新、削除
  • イシューへのラベルの追加
  • イシューからのラベルの削除

• マイルストーン管理

  • プロジェクトのマイルストーンの取得
  • マイルストーンの新規作成

• ユーザーの割り当て

  • イシューへのユーザーの割り当て
  • イシューからの担当者の削除

• イシューの関連付け

  • イシュー間のリンクの作成
  • イシューのリンクの削除

インストール

グローバルインストール

npm install -g @piatra-open-source/gitlab-mcp-server

プロジェクトへのインストール

npm install @piatra-open-source/gitlab-mcp-server

使用方法

環境変数

次の環境変数を設定する必要があります。

• GITLAB_PERSONAL_ACCESS_TOKEN：適切な権限を持つ GitLab のパーソナルアクセストークン
• GITLAB_API_URL（省略可）：gitlab.com 以外を使用する場合のカスタム GitLab API URL（デフォルトは 'https://gitlab.com/api/v4'）

サーバーの実行

export GITLAB_PERSONAL_ACCESS_TOKEN='your_token_here'
gitlab-mcp-server

または、アプリケーション内で次のように実行します。

import { execFileSync } from 'child_process';
import { join } from 'path';

// Path to the GitLab MCP Server binary
const serverPath = join(require.resolve('@piatra-open-source/gitlab-mcp-server'), '..', '..', 'bin', 'gitlab-mcp-server');

// Start the server
const childProcess = execFileSync(serverPath, {
  env: {
    ...process.env,
    GITLAB_PERSONAL_ACCESS_TOKEN: 'your_token_here'
  }
});

API リファレンス

関数

関数名	説明
create_repository	新しい GitLab プロジェクトを作成します
update_project	可視性を含むプロジェクト設定を更新します
delete_project	GitLab プロジェクトを削除します
search_repositories	GitLab プロジェクトを検索します
get_file_contents	ファイルまたはディレクトリの内容を取得します
create_or_update_file	単一のファイルを作成または更新します
push_files	複数のファイルを一度にコミットします
create_branch	新しいブランチを作成します
fork_repository	プロジェクトをフォークします
create_issue	新しいイシューを作成します
create_merge_request	新しいマージリクエストを作成します
get_issues	フィルタリングオプションを指定して、プロジェクトのイシューを取得します
get_issue	詳細情報を含む単一のイシューを取得します
get_issue_time_stats	イシューの時間追跡統計を取得します
set_time_estimate	イシューの作業時間見積もりを設定します
reset_time_estimate	イシューの作業時間見積もりをリセットします
add_spent_time	イシューに作業時間を追加します
reset_spent_time	イシューの作業時間をリセットします
get_notes	イシューのコメント／ノートを取得します
create_note	イシューにコメントを作成します
update_note	既存のコメントを更新します
delete_note	イシューのコメントを削除します
update_issue	イシューの各種属性を更新します
close_issue	イシューをクローズします
reopen_issue	クローズ済みのイシューを再オープンします
get_project_labels	プロジェクトのすべてのラベルを取得します
create_project_label	プロジェクトに新しいラベルを作成します
update_project_label	既存のラベルを更新します
delete_project_label	プロジェクトのラベルを削除します
add_labels_to_issue	指定したラベルをイシューに追加します
remove_labels_from_issue	指定したラベルをイシューから削除します
get_project_milestones	プロジェクトのすべてのマイルストーンを取得します
create_project_milestone	プロジェクトに新しいマイルストーンを作成します
assign_issue	イシューにユーザーを割り当てます
unassign_issue	イシューからすべての担当者を削除します
create_issue_link	2 つのイシュー間にリンクを作成します
delete_issue_link	イシュー間のリンクを削除します

使用例

// Example: Create a repository in a specific group
const repo = await claude.callMcp("gitlab", "create_repository", {
  name: "my-new-project",
  description: "A new project created via MCP",
  visibility: "private",
  initialize_with_readme: true,
  namespace_id: "12345678"  // Group ID where the project should be created
});

// Example: Change project visibility
const updatedRepo = await claude.callMcp("gitlab", "update_project", {
  project_id: "12345678",
  visibility: "private"
});

// Example: Delete a project
const deleteResult = await claude.callMcp("gitlab", "delete_project", {
  project_id: "12345678"
});

// Example: Get all issues with time tracking stats
const issues = await claude.callMcp("gitlab", "get_issues", {
  project_id: "12345678",
  state: "opened",
  with_time_stats: true
});

// Example: Add spent time to an issue
const timeStats = await claude.callMcp("gitlab", "add_spent_time", {
  project_id: "12345678", 
  issue_iid: 42,
  duration: "1h 30m" // Format: Xh Ym
});

// Example: Get all comments on an issue
const notes = await claude.callMcp("gitlab", "get_notes", {
  project_id: "12345678",
  issue_iid: 42,
  sort: "desc",
  order_by: "created_at"
});

// Example: Update an issue
const updatedIssue = await claude.callMcp("gitlab", "update_issue", {
  project_id: "12345678",
  issue_iid: 42,
  title: "Updated issue title",
  description: "This is the updated description"
});

// Example: Create a label
const newLabel = await claude.callMcp("gitlab", "create_project_label", {
  project_id: "12345678",
  name: "enhancement",
  color: "#428BCA",
  description: "Enhancement requests"
});

// Example: Add labels to an issue
const issueWithLabels = await claude.callMcp("gitlab", "add_labels_to_issue", {
  project_id: "12345678",
  issue_iid: 42,
  labels: ["bug", "enhancement"]
});

// Example: Create a milestone
const milestone = await claude.callMcp("gitlab", "create_project_milestone", {
  project_id: "12345678",
  title: "v1.0 Release",
  description: "First stable release",
  due_date: "2025-06-30"
});

// Example: Assign users to an issue
const assignedIssue = await claude.callMcp("gitlab", "assign_issue", {
  project_id: "12345678",
  issue_iid: 42,
  assignee_ids: [123, 456]
});

// Example: Create a link between issues
const issueLink = await claude.callMcp("gitlab", "create_issue_link", {
  project_id: "12345678",
  issue_iid: 42,
  target_project_id: "12345678",
  target_issue_iid: 43,
  link_type: "relates_to"
});

元の実装からの改善点

この実装には、元の MCP GitLab サーバーに対するいくつかの改善が含まれています。

1. 包括的な API エンドポイント：

   • delete_project：GitLab プロジェクトを適切に削除します
   • update_project：可視性を含むプロジェクト設定を更新します
   • get_issues と get_issue：フィルタリングオプションを指定してイシューを取得します
   • 時間追跡エンドポイント：見積もりや作業時間を設定／リセットします
   • ノートエンドポイント：コメントを作成、読み取り、更新、削除します
   • ラベル管理：ラベルの作成、取得、更新、削除を行います
   • マイルストーン管理：マイルストーンを取得し、新しいものを作成します
   • ユーザーの割り当て：イシューへのユーザーの割り当てと解除を行います
   • イシューの関連付け：イシュー間のリンクを作成、削除します

2. namespace_id の処理を修正：

   • グループの名前空間でのプロジェクト作成を適切にサポートします
   • namespace_id を検証し、GitLab API に渡します

3. エラー処理を強化：

   • API の応答データを含む詳細なエラーメッセージ
   • 入力パラメーターの検証を改善
   • 認証や権限に関する問題へのフィードバックを改善

4. ドキュメントを更新：

   • サポートされているすべてのパラメーターを明確に記載
   • より完全な型定義

トラブルシューティング

"file_path should be a valid file path" エラー

GitLab API error (400): Bad Request - file_path should be a valid file path エラーが発生した場合、いくつかの原因が考えられます。

1. ファイルパスの形式：GitLab では、有効で適切な形式のファイルパスが必要です。ファイルパスが次の条件を満たしていることを確認してください。

   • *、?、[、] などの無効な文字が含まれていない
   • バックスラッシュ（\）ではなく、スラッシュ（/）を使用している
   • 適切に URL エンコードされている（このライブラリで処理されます）

2. 大文字と小文字の区別：GitLab のファイルパスでは大文字と小文字が区別されます。既存ファイルの正確な大文字と小文字にパスが一致していることを確認してください。

3. リポジトリ構成：更新する場合、ファイルパスはリポジトリ構成内に存在する必要があります。新しいファイルの場合は、有効なパスである必要があります。

4. 特殊文字：可能な場合は、ファイル名に特殊文字を使用しないでください。#、?、[、] などの文字を使用する必要がある場合は、特別な処理が必要になる可能性があることに注意してください。

その他のよくある問題

• 認証の失敗：GITLAB_PERSONAL_ACCESS_TOKEN に必要な権限があることを確認してください。
• アクセス許可の拒否：リポジトリとグループへの適切なアクセス権があることを確認してください。
• レート制限：GitLab API にはレート制限があり、上限を超えると一時的にアクセスがブロックされる場合があります。

ライセンス

MIT

謝辞

このプロジェクトは、Anthropic によるオリジナルの Model Context Protocol GitLab server を MIT ライセンスのもとで変更・拡張したものです。