GitLab MCP Server (noqta-gitlab-server)

GitLab MCP サーバー（noqta-gitlab-server）

GitLab API と連携するためのツールを提供する Model Context Protocol (MCP) サーバーです。

このサーバーを使用すると、AI アシスタント（MCP 統合を通じた Claude など）が、自然言語のコマンドで GitLab 上のリポジトリの検索、イシューの管理、ブランチの作成など、さまざまな操作を直接実行できます。

機能／利用可能なツール

このサーバーは、MCP クライアントが使用できる以下のツールを公開します。

• search_repositories：名前で GitLab プロジェクトを検索します。
• get_project_from_git_url：Git リモート URL から GitLab プロジェクトの詳細を取得します。
• list_issues：特定の GitLab プロジェクトのイシューを一覧表示します（状態、ラベル、担当者、スコープで絞り込み可能）。
• get_my_issues：認証済みユーザーが担当または作成した、すべてのプロジェクトにわたるイシューを一覧表示します（状態、スコープで絞り込み可能）。
• get_issue：IID を指定して、プロジェクト内の特定のイシューの詳細を取得します。
• create_issue_note：特定のイシューにコメント（ノート）を追加します。
• update_issue：イシューの属性（タイトル、説明、ラベル、状態など）を更新します。
• bulk_update_issues：プロジェクト内の複数のイシューの属性を一括更新します。
• create_branch：指定した参照から、プロジェクトに新しいブランチを作成します。
• create_issue：プロジェクトに新しいイシューを作成します。
• list_documentation_wiki_pages：設定済みのドキュメントプロジェクトのドキュメント Wiki ページを一覧表示します。
• get_documentation_wiki_page：設定済みのドキュメントプロジェクトから、スラッグを指定してドキュメント Wiki ページを取得します。
• list_wiki_pages：特定の GitLab プロジェクトの Wiki ページを一覧表示します（デフォルトは DOC_WIKI_PROJECT_PATH）。
• create_merge_request：新しいマージリクエストを作成します。
• list_issue_notes：特定のイシューのコメント（ノート）を一覧表示します。
• create_merge_request_note：特定のマージリクエストにコメント（ノート）を追加します。
• search_user：メールアドレスまたはユーザー名で GitLab ユーザーを検索します。
• create_repository：ユーザーまたはグループのネームスペースに新しい GitLab プロジェクト（リポジトリ）を作成します。

（各ツールの入力スキーマの詳細については、サーバーの ListTools の応答またはソースコード（src/index.ts）を参照してください。）

前提条件

• Node.js（LTS バージョンを推奨）
• npm（通常は Node.js に含まれています）
• GitLab アカウント（gitlab.com またはセルフホスト）
• api および read_api スコープを持つ GitLab Personal Access Token。

インストールとセットアップ

1. リポジトリをクローンします：

   git clone https://github.com/nooqta/noqta-gitlab-server.git # Replace with actual URL after creation
   cd noqta-gitlab-server
   

2. 依存関係をインストールします：

   npm install
   

3. 環境変数を設定します：

   • サンプル環境ファイルをコピーします：

     cp .env.example .env
     

   • .env ファイルを編集します：
     • GitLab Personal Access Token を生成します：GitLab プロフィールから Settings -> Access Tokens に移動します。api および read_api スコープを持つトークンを作成します。
     • 生成したトークンを .env の GITLAB_PERSONAL_ACCESS_TOKEN 変数に貼り付けます。
     • （任意） セルフホストの GitLab インスタンスを使用する場合は、GITLAB_API_URL をインスタンスの API エンドポイント（例：https://gitlab.yourcompany.com/api/v4）に変更します。それ以外の場合は、gitlab.com のデフォルト値のままにします。
     • （任意） Wiki のホームページ URL を DOC_WIKI_HOME_URL に設定します。DOC_WIKI_PROJECT_PATH が設定されていない場合は、この URL から導出されます。

4. サーバーをビルドします：

   npm run build
   

   これにより、TypeScript コードが build/ ディレクトリ内の JavaScript にコンパイルされます。

サーバーの実行

Node.js で直接実行する（クローンとビルドの後）

リポジトリをクローンしてプロジェクトをビルド済み（npm run build）であれば、サーバーを直接実行できます：

node build/index.js

npx を使用する（npm への公開後）

パッケージが npm に（@nooqta/gitlab-mcp-server として）公開されたら、クローンや手動でのインストールをせずに、npx を使って直接実行できます。npx がパッケージをダウンロードして実行します。

npx @nooqta/gitlab-mcp-server

注： npx 経由で実行する場合も、サーバーには環境変数（GITLAB_PERSONAL_ACCESS_TOKEN および任意の GITLAB_API_URL）が必要です。npx コマンドを実行する環境に設定するか、npx を実行するディレクトリにある .env ファイルから読み込めるようにしてください。

サーバーは標準入出力（stdio）を介して通信します。継続的に使用する場合は、pm2 や systemd などのプロセスマネージャーで実行することを検討してください。

統合（例：Claude Desktop）

このサーバーを Claude Desktop などの MCP クライアントで使用するには、クライアントの設定ファイルに構成を追加してください。

設定ファイルの場所：

• MacOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

npx を使用する場合の claude_desktop_config.json の設定例：

{
  "mcpServers": {
    "@nooqta/gitlab-mcp-server": {
      "command": "npx",
      "args": ["-y", "@nooqta/gitlab-mcp-server"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "...",
        "GITLAB_API_URL": "..."
      }
    }
  }
  // Potentially other configurations...
}

ローカルビルドを使用する場合の claude_desktop_config.json の設定例：

{
  "mcpServers": {
    "@nooqta/gitlab-mcp-server": {
      // Use the package name for consistency, even if running locally
      "command": "/full/path/to/your/custom-gitlab-server/build/index.js",
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "...",
        "GITLAB_API_URL": "..."
      }
    }
    // Potentially other configurations...
  }
}

重要なセキュリティに関する注意： このサーバーは dotenv を使用して、.env ファイルから GITLAB_PERSONAL_ACCESS_TOKEN と GITLAB_API_URL を読み込みます。実際のトークンや機密性の高い URL を、env プロパティを使って claude_desktop_config.json のような MCP クライアントの設定ファイルに直接記述してはいけません。必ず .env ファイル（ローカルで実行する場合はサーバーのプロジェクトディレクトリ、npx を実行する場合はそのディレクトリに配置）を使用するか、オペレーティングシステムの環境変数を通じて値を指定してください。

開発

• ビルド： npm run build（TypeScript をコンパイルし、実行権限を設定します）
• 監視モード： npm run watch（ファイルの変更時に自動で再コンパイルします）

デバッグ

MCP サーバーは stdio を介して通信するため、直接デバッグするのは難しい場合があります。デバッグを簡単にするには、MCP Inspector を使用してください。

npm run inspector

このコマンドは、Inspector を接続した状態でサーバーを起動します。コンソール出力に表示される URL をブラウザーで開くと、MCP メッセージとサーバーログを確認できます。

ライセンス

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

貢献

皆さまからの貢献を歓迎します。ガイドラインについては CONTRIBUTING.md ファイルをご覧ください。