MCP Aggregator

MCP アグリゲーター

複数の MCP サーバーを単一のインターフェースにまとめられる、MCP（Model Context Protocol）アグリゲーターです。コードの大部分は AI によって生成されています。

MCP サーバーをまとめる理由

このアプリの主な目的は、一度に使用できる MCP サーバーが 2 つまでという Cursor の制限を回避することでした。私の場合、どのサーバーであっても、3 つ目の MCP サーバーを追加すると、ほかの 2 つのうち 1 つが使えなくなっていました。

概要

MCP アグリゲーターは、Cursor（またはほかの MCP クライアント）と複数の MCP サーバーをつなぐブリッジとして機能します。Cursor との通信時には MCP サーバーとして、バックエンドの MCP サーバーとの通信時には MCP クライアントとして動作します。

主な機能：

• Cursor やほかの MCP クライアント向けに stdio インターフェースを提供します
• 複数のバックエンド MCP サーバーに接続します
• バックエンドサーバーのメソッドにプレフィックスを付けます（例：「shortcut」MCP の「search_stories」メソッドを「shortcut_search_stories」にします）
• Cursor との互換性を保つため、ダッシュをアンダースコアに置き換えてツール名を自動的にサニタイズします
• 環境変数と JSON 設定ファイルで設定できます
• ログレベルを設定できるデバッグログを提供します

インストール

インストールスクリプトを使用する（推奨）

インストールスクリプトを使用して、combine-mcp の最新バージョンをインストールできます。

# Download and run the installation script
curl -fsSL https://raw.githubusercontent.com/nazar256/combine-mcp/main/install.sh | bash

# Or install a specific version
curl -fsSL https://raw.githubusercontent.com/nazar256/combine-mcp/main/install.sh | bash -s -- -v v1.0.0

スクリプトは次の処理を行います。

• オペレーティングシステムとアーキテクチャを検出します
• 適切なコンパイル済みバイナリをダウンロードします
• チェックサムを検証します
• PATH 内の適切な場所にインストールします
• 実行可能にします

go install を使用する（代替方法）

# Install directly from GitHub (binary will be placed in $GOPATH/bin)
go install github.com/nazar256/combine-mcp/cmd/combine-mcp@latest

# Ensure $GOPATH/bin is in your PATH
# For example, add this to your .bashrc or .zshrc:
# export PATH=$PATH:$(go env GOPATH)/bin

Docker を使用する（代替方法）

ローカルにインストールせずに、Docker を使用して combine-mcp を直接実行できます。

# Run the latest version
docker run --rm -v ~/.config/mcp:/config ghcr.io/nazar256/combine-mcp:latest

# Run a specific version
docker run --rm -v ~/.config/mcp:/config ghcr.io/nazar256/combine-mcp:v1.0.0

# Set environment variables
docker run --rm -v ~/.config/mcp:/config -e MCP_CONFIG=/config/config.json -e MCP_LOG_LEVEL=debug ghcr.io/nazar256/combine-mcp:latest

Cursor で使用するには、Docker を使うように MCP サーバーを設定する必要があります。

{
  "mcpServers": {
    "aggregator": {
      "command": "docker",
      "args": ["run", "--rm", "-v", "~/.config/mcp:/config", "ghcr.io/nazar256/combine-mcp:latest"],
      "env": {
        "MCP_CONFIG": "/config/config.json"
      }
    }
  }
}

Makefile を使用する

このプロジェクトには、一般的なタスク用の Makefile が含まれています。

# Build the binary
make build

# Run tests
make test

# Clean up build artifacts
make clean

使い方

アグリゲーターを設定する

既存の Cursor MCP 設定を任意の場所（例：~/.config/mcp/config.json）にコピーできます。設定は次のようになります。

Cursor ユーザーにとって便利な機能として、MCP サーバーのツールをフィルタリングできます。これにより、Cursor のツール数上限である 40 個を超えないように管理し、Cursor に使わせたくないツールを公開しないようにできます。

{
  "mcpServers": {
    "shortcut": {
      "command": "npx",
      "args": ["-y", "@shortcut/mcp"],
      "env": {
        "SHORTCUT_API_TOKEN": "your-shortcut-api-token-here"
      },
      "tools": {
        "allowed": ["search-stories", "get-story", "create-story"]
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here"  
      }
    }
  }
}

Cursor でアグリゲーターを設定する

Cursor の設定では、MCP サーバーをアグリゲーター 1 つだけにできます。設定は次のようになります（combine-mcp バイナリが PATH にインストール済みで、~/.config/mcp/config.json ファイルがある場合）。

{
  "mcpServers": {
    "aggregator": {
      "command": "combine-mcp",
      "env": {
        "MCP_CONFIG": "~/.config/mcp/config.json"
      }
    }
  }
}

環境変数

• MCP_CONFIG：設定ファイルのパス（必須）
• MCP_LOG_LEVEL：ログレベル（error、info、debug、trace）— デフォルト：info
• MCP_LOG_FILE：ログファイルのパス
• MCP_PROTOCOL_VERSION：互換性のために特定のプロトコルバージョンを強制します
• MCP_CURSOR_MODE：Cursor 固有の互換性調整を有効にします

ユースケース

複数クライアント向けの統一 MCP 設定

実用的なユースケースの 1 つは、MCP 対応クライアント（例：Cursor、Windsurf、Gemini-CLI、Codex、Claude Code、GitHub Copilot agents など）で共有する単一の MCP 設定ファイルを管理することです。

クライアントごとに MCP サーバーの一覧を設定し、シークレットを重複して登録する代わりに、次のようにします。

• バックエンド MCP サーバー（およびそのシークレット）を、アグリゲーターの設定で一度だけ設定します。
• 各クライアントから、同じ MCP_CONFIG ファイルを指定した同一の combine-mcp バイナリを使うようにします。
• すべてのクライアント向けに、アグリゲーターがツールのプレフィックス付与、フィルタリング、正規化を行うようにします。

これには次のような利点があります。

• 利用可能な MCP サーバーとツールの信頼できる唯一の情報源を 1 つにできます。
• シークレットを一元管理できます。API トークンなどの認証情報は、アグリゲーターの設定にのみ保存されます。
• クライアントごとに MCP を再設定することなく、異なる IDE／エージェント間で一貫した動作を実現できます。
• シークレットを分離できます。シークレットを AI エージェントのツールと直接共有する必要はありません。

ツール名のサニタイズ

MCP Aggregator は、ハイフンをアンダースコアに置き換えて、ツール名を自動的にサニタイズします。これは、Cursor にはツール名にハイフンが含まれるツールを正しく検出または使用できない既知の問題があるため必要です。

たとえば：

• 元のツール名：get-user
• サニタイズ後のツール名：get_user
• プレフィックス付きのツール名（ショートカットサーバーの場合）：shortcut_get_user

サニタイズは透過的に行われます。サニタイズ後の名前でツールを呼び出すと、アグリゲーターはバックエンドサーバーにリクエストを転送する際に、元の名前に対応付けます。

ツールのフィルタリング

MCP Aggregator は、サーバーごとに任意のツールフィルタリングをサポートしています。これは、次のような場合に便利です：

• Cursor のツール上限（最大 40 ツール）を超えないよう、公開するツール数を制限する
• 各サーバーから特定のツールだけを公開する
• サーバー間のツール名の競合を避ける
• 処理するツール数を減らしてパフォーマンスを向上させる

ツールのフィルタリングを有効にするには、公開するツールを列挙した allowed 配列を含む tools オブジェクトを、サーバー設定に追加します：

{
  "mcpServers": {
    "shortcut": {
      "command": "npx",
      "args": ["-y", "@shortcut/mcp"],
      "env": {
        "SHORTCUT_API_TOKEN": "your-shortcut-api-token-here"
      },
      "tools": {
        "allowed": [
          "search-stories",
          "get-story",
          "create-story",
          "assign-current-user-as-owner"
        ]
      }
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "your-github-token-here"
      },
      "tools": {
        "allowed": [
          "create-pr",
          "list-prs",
          "get-pr",
          "merge-pr"
        ]
      }
    }
  }
}