🚀 MetaMCP (MCPアグリゲータ、オーケストレータ、ミドルウェア、ゲートウェイをひとつのdockerにまとめた)

📢 最新情報: このai-devブランチは、今後AIエージェントの変更が含まれる開発用ブランチです。イメージをこのブランチに基づいてビルドする前に、テストを行ってください。コミュニティからの多くのPRがありますが、それらのマージとレビューも負担が増えています。AI関連の変更を含めることにしました。少なくとも現時点では、コア機能は動作しています。コミュニティによってメンテナンスされているフォークも存在します（ありがとうございます！）：https://github.com/Umbrella-IT-Group/metamcp

📢 更新: [[作者より: 最近のメンテナンスが遅れて申し訳ございません。少なくともPRのマージは続けていきます。背景はこちら]

MetaMCP は、MCPサーバーを動的に集約して単一のMCPサーバーとして公開し、ミドルウェアを適用できるMCPプロキシです。MetaMCP自体がMCPサーバーであるため、どのような MCPクライアントにも簡単に接続できます。

詳細については、当社のドキュメントサイトをご覧ください: https://docs.metamcp.com

English | 简体中文

📋 目次

• 🎯 ユースケース

• 📖 概念

  • 🖥️ MCPサーバー

    • 🔐 環境変数とシークレット (STDIO MCPサーバー)

  • 🏷️ MetaMCP名前空間

  • 🌐 MetaMCPエンドポイント

  • ⚙️ ミドルウェア

  • 🔍 インスペクタ

  • ✏️ ツールのオーバーライドと注釈

• 🚀 クイックスタート

  • 🐳 Docker Composeで実行（推奨）

  • 📦 Dev Containers (VSCode/Cursor) で開発環境を構築

  • 💻 ローカル開発

• 🔌 MCPプロトコル互換性

• 🔗 MetaMCPに接続する

  • 📝 例: mcp.jsonを利用したCursor接続

  • 🖥️ Claude Desktopおよびその他のSTDIO専用クライアントに接続

  • 🔧 APIキー認証のトラブルシューティング

• ❄️ コールドスタートの問題とカスタムDockerfile

• 🧾 ログレベル

• 🔐 認証

• 🚦 トラフィック管理

  • 🚧 MCPレート制限

• 🔗 OpenID Connect (OIDC) プロバイダーサポート

  • 🛠️ 設定

  • 🏢 対応プロバイダー

  • 🔒 セキュリティ機能

  • 📱 利用方法

• ⚙️ 登録制御

  • 🎛️ 利用可能な制御

  • 🏢 エンタープライズユースケース

  • 🛠️ 設定

• 🌐 カスタムデプロイとNginxのSSE設定

• 🏗️ アーキテクチャ

  • 📊 シーケンス図

• 🗺️ ロードマップ

• 🌐 i18n

• 🤝 コントリビューション

• 📄 ライセンス

• 👏 クレジット

Related MCP server: Master MCP Server

🎯 ユースケース

• 🎯 MCPサーバーを名前空間にグループ化し、メタMCPとしてホストし、認証付きのパブリックエンドポイント（SSEまたはStreamable HTTP）を割り当てる。エンドポイントの名前空間をワンクリックで切り替え可能。

• 🎯 MCPサーバーを再構成する際に、必要なツールだけを選択する。 可観測、セキュリティなどに関するプラグイン可能なミドルウェアを適用します (近日追加予定)。

• 🔍 保存済みのサーバー設定を持つ拡張MCPインスペクタとして使用し、自分のMetaMCPエンドポイントを社内で検査して、動作するかを確認できます。

• 🔍 MCPツール選択用のElasticsearchとして使用（近日追加予定）

一般的に、開発者はMetaMCPをインフラストラクチャとして使用し、動的に構成されたMCPサーバーを統一されたエンドポイントでホストし、その上にエージェントを構築できます。

Quick demo video: https://youtu.be/Cf6jVd2saAs

📖 概念

🖥️ MCPサーバー

MetaMCPにMCPサーバーをどのように起動するかを指示するMCPサーバー構成です。

"HackerNews": {
  "type": "STDIO",
  "command": "uvx",
  "args": ["mcp-hn"]
}

🔐 環境変数とシークレット (STDIO MCPサーバー)

STDIO MCPサーバーの場合、MetaMCPは環境変数とシークレットを処理する3つの方法をサポートしています。

1. 生データ – 文字列で直接指定する方法（シークレットには非推奨の）。

API_KEY=your-actual-api-key-here
DEBUG=true

2. 環境変数参照 – ${ENV_VAR_NAME} 構文を使用する方法：

API_KEY=${OPENAI_API_KEY}
DATABASE_URL=${DB_CONNECTION_STRING}

3. 自動マッチング – ツールが期待する環境変数名とコンテナの環境変数名が一致する場合、その環境変数を省略できる。 MetaMCPは、一致する環境変数を自動的に渡します。

🔒 セキュリティノート: 環境変数参照（${VAR_NAME}）は、実行時にMetaMCP環境から解決されます。これにより、実際のシークレット値を設定やgitリポジトリに含めないようにできます。

⚙️ 開発ノート: ローカル開発で pnpm run dev:docker を利用するには、環境変数が turbo.json の globalEnv に含まれ、開発プロセスに渡されるようにします。これは、.dockor production デプロイでは必要ありません。

🏷️ MetaMCP名前空間

• 複数のMCPサーバーを名前空間にグループ化

• MCPサーバーまたはツールごとに有効/無効を設定

• MCPのリクエストとレスポンスにミドルウェアを適用

• 名前空間ごとにツール名/タイトル/説明をオーバーライドし、カスタムMCPアノテーションを追加（例: { "annotations": { "readOnlyHint": false } }）

🌐 MetaMCPエンドポイント

• エンドポイントを作成し、名前空間をエンドポイントに割り当て

• 名前空間内の複数のMCPサーバーが集約され、MetaMCPエンドポイントとして提供されます

• ヘッダーまたはクエリパラメータによるAPIキー認証または、MCP Spec 2025-06-18 に基づく標準OAuthを選択

• MCPのSSEまたはStreamable HTTP転送、およびOpen WebUIなどのクライアント向けのOpenAPI エンドポイントを通じてホスト

⚙️ ミドルウェア

• MCPリクエストとレスポンスを名前空間レベルでインターセプト、変換します。

• 組み込みの例: "inactive tools のフィルター" – LLMのツールコンテキストを最適化

• 将来のアイデア: ツールクリギング、エラー呼び出しの記録トレース、検証、スキャン

🔍 インスペクタ

公式のMCPインスペクタに似ていますが、server settings を保存できます。MetaMCPが自動で設定を作成するので、MetaMCP のエンドポイントをすぐにデバッグできます。

✏️ ツールオーバーライドとアノテーション

• 名前空間を開き、 ツール タブから接続済みのMCPサーバーにあるツールをすべて表示できます。

• 保存された各ツールを展開してインライン編集でき、表示名前/タイトル/説明を更新したり、名前空間固有のアノテーションを持つJSON形式を提供したりできます（例: { "annotations": { "readOnlyHint": false } }）。

• 表のバッジ（オーバーライド済み、アノテーション）は、カスタムメタフィールドを持つツールを示します。ホバーすると、オーバーライドされた内容がツールチップで表示されます。

• アノテーションのオーバーライドは、上流のMCPサーバーが返す内容と比較読み込みますので、提供元のメタデータを損失することなくカスタムUIヒントをら安全に安全を追加できます。

🚀 クイックスタート

🐳 Docker Compose で起動 (推奨)

リポジトリを clone し、.env を作成し、docker compose で起動してください。

git clone https://github.com/fanywebfx/metamcp.git
cd metamcp
cp example.env .env
docker compose up -d
# pulls ghcr.io/fanywebfx/metamcp:ai-dev

もし APP\_URL 環境変数を変更した場合は、必ずそのAPP\_URL からのにアクセスするようにしてください。MetaMCPはCORSポリシーを適用するため、他のURLからはアクセスできません。

SQLiteデータはCompose volume (sqlite_data) に保存されます。別のプロジェクトと名前が衝突する場合は、docker-compose.yml でそのvolumeを名称を変更してください。

📦 Dev Containers (VSCode/Cursor) で開発環境を構築する

VSCode/Cursor 拡張機能を使えば、コンテナ内で開発環境を構築できます。

必要なのは、Docker（または同等の代替）を実行する環境のみです（docker/docker compose コマンドが必須）。追加の依存コンポーネントをホストマシンにインストールする必要はありません。

1. まず、MetaMCPソースコードをクローンし、Visual Studio Codeでプロジェクトを開きます。

git clone https://github.com/fanywebfx/metamcp.git
cd metamcp
code .

2. Dev Containers に切り替えます。VSCodeのコマンドパレットを開き、Dev Containers: Reopen in Container を実行します。

事前に .env を作成する必要はありません。コンテナは生成時に example.env を .env.local にコピーし、依存関係をインストールし、SQLite ファイルをマイグレーションします。

VSCodeは新しいウィンドウで Dev Containers プロジェクトを開き、Dockerfile に従って実行環境とツールチェインを構築し、接続開始後に MetaMCPの依存関係をインストールします。

注意 このプロセスには安定したネットワークの接続が必要です。Docker Hub、GitHub などのサイトにアクセスしてのために、ご自分でネットワーク接続の準備をしてください。 そうしないとコンテナのビルドが失敗。

しばらくお待ちください。ネットワークやコンピュータの性能によって、数分から数十分かかります。右下のプログレスバーをクリックすると、ライブログを確認でき、異常な停滞をチェックできます。

終了後、pnpm dev を実行して開発サーバーを起動できます。

💻 ローカル開発

SQLiteは自動的に data/metamcp.ref に作成されます（バックエンドの作業ディレクトリに相対。ただし、DATABASE_PATHを設定した場合を除く）。

cp example.env .env.local
pnpm install
cd apps/backend && pnpm db:migrate:dev && cd ../..
pnpm dev

🔌 MCP プロトコル互換性

• ✅ ツール、リソース、プロンプト がサポートされています

• ✅ OAuth 対応 MCP サーバー は 03-26 バージョンでテスト済み

質問があれば、お気軽に GitHub issues または PR をお送りください。

🔗 MetaMCP に接続

📝 例: mcp.json 経由の Cursor

mcp.json の例

{
  "mcpServers": {
    "MetaMCP": {
      "url": "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
    }
  }
}

🖥️ Claude Desktop およびその他の STDIO 専用クライアントの接続

MetaMCP のエンドポイントはリモート専用（SSE、Streamable HTTP、OpenAPI）であるため、stdio サーバーのみをサポートするクライアント（Claude Desktop など）は接続にローカルプロキシが必要です。

注: この目的で mcp-remote が提案されることがありますが、これは OAuth ベースの認証向けに設計されており、MetaMCP の API キー認証では動作しません。テストの結果、mcp-proxy が推奨される解決策です。

mcp-proxy を使用した Claude Desktop の動作する設定は次のとおりです:

Streamable HTTP を使用する場合

{
  "mcpServers": {
    "MetaMCP": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "--transport",
        "streamablehttp",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/mcp"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

SSE を使用する場合

{
  "mcpServers": {
    "ehn": {
      "command": "uvx",
      "args": [
        "mcp-proxy",
        "http://localhost:12008/metamcp/<YOUR_ENDPOINT_NAME>/sse"
      ],
      "env": {
        "API_ACCESS_TOKEN": "<YOUR_API_KEY_HERE>"
      }
    }
  }
}

重要な注意事項:

• <YOUR_ENDPOINT_NAME> を実際のエンドポイント名に置き換えてください

• <YOUR_API_KEY_HERE> を MetaMCP API キー（形式: sk_mt_...）に置き換えてください

詳細や代替アプローチについては、issue #76 を参照してください。

🔧 API キー認証のトラブルシューティング

• ?api_key= パラメータによる API キー認証は SSE では機能しません。Streamable HTTP と OpenAPI でのみ機能します。

• ベストプラクティスは、Authorization: Bearer <API_KEY> ヘッダーで API キーを使用することです。

• 接続の問題が発生した場合は、認証を一時的に無効にして、認証の問題かどうかを確認してください。

❄️ コールドスタート問題とカスタム Dockerfile

• MetaMCP は、設定された各 MCP サーバーと MetaMCP に対してアイドルセッションを事前に割り当てます。各セッションのデフォルトのアイドル数は 1 で、コールドスタート時間の短縮に役立ちます。

• MCP が uvx や npx 以外の依存関係を必要とする場合は、Dockerfile をカスタマイズして依存関係を自分でインストールする必要があります。

• 更新中にアイドルセッションがどのように無効化されるかについてのシーケンス図は、invalidation.md を参照してください。

🛠️ 解決策: Dockerfile をカスタマイズして依存関係を追加するか、パッケージを事前インストールしてコールドスタート時間を短縮します。

🧾 ログレベル

MetaMCP のバックエンドはログをファイルに書き込み、オプションで選択したレベルをコンソールにミラーリングします。コンソールへのミラーリングは LOG_LEVEL 環境変数で制御します。

• ファイル

  • app.log: DEBUG、INFO、WARN を受け取ります

  • error.log: ERROR を受け取ります

• コンソールへのミラーリング（LOG_LEVEL）

  • all: DEBUG、INFO、WARN、ERROR をコンソールにミラーリング

  • info: INFO のみをコンソールにミラーリング

  • errors-only: WARN と ERROR をコンソールにミラーリング

  • none: コンソール出力なし

• デフォルトと例

  • デフォルト（未設定または無効な場合）: errors-only

  • .env の例:

    LOG_LEVEL='errors-only' # 'all', 'info', 'errors-only', 'none'

  • docker-compose.dev.yml では: LOG_LEVEL: ${LOG_LEVEL:-all} を使用

🔐 認証

• 🛡️ Better Auth によるフロントエンドとバックエンド（TRPC プロシージャ）の認証

• 🍪 セッションクッキー により、安全な内部 MCP プロキシ接続を強制します

• 🔑 API キー認証 による Authorization: Bearer <api-key> ヘッダー経由の外部アクセス

• 🪪 MCP OAuth: 公開されたエンドポイントには、MCP Spec 2025-06-18 の標準 OAuth を使用するオプションがあり、簡単に接続できます。

• 🏢 マルチテナンシー: 組織が自社のマシンにデプロイできるように設計されています。プライベートとパブリックの両方のアクセススコープをサポートします。ユーザーは自分自身または全員のために MCP、名前空間、エンドポイント、API キーを作成できます。パブリック API キーはプライベート MetaMCP にアクセスできません。

• ⚙️ 登録の個別制御: 管理者は設定ページから UI 登録と SSO/OAuth 登録を個別に制御でき、柔軟なエンタープライズ展開シナリオを実現できます。

🚦 トラフィック管理

🚧 MCP レート制限

MCP レート制限機能を使用すると、MCP ツール（エンドポイント）が特定の時間枠内で受け入れる最大リクエスト数を設定できます。制限を設定するには、個別にまたは一緒に使用できる 2 つの異なる戦略があります:

• Endpoint rate-limiting (Rate Limiting): エンドポイントを使用するすべてのクライアントに同時に適用され、一意のカウンターを共有します。

• User rate-limiting (Client Rate Limiting): 個々のユーザーごとにカウンターを設定します。

両方のタイプは共存でき、互いに補完し合い、カウンターをインメモリに保存します。クラスター上では、各マシンは通過するトラフィックのみを認識してカウントします。

エンドポイントレート制限

エンドポイントレート制限は、エンドポイントが処理できる同時トランザクション数に作用します。このタイプの制限は、すべての顧客のサービスを保護します。

エンドポイントに接続しているユーザーが合計で rate-limiting を超えると、MetaMCP はステータスコード 503 Service Unavailable で接続を拒否し始めます。

エンドポイントレート制限のオプション

• Max Rate: 任意の時点で全ユーザーから同時に受け入れるリクエスト数を定義します。ゲートウェイが起動すると、バケットは満杯です。ユーザーからのリクエストが来ると、バケット内の残りトークンが減少します。同時に、レート制限は最大容量に達するまで、希望するレートでバケットを補充します。

• Max Rate Seconds: 最大レートが動作する時間（秒単位）。たとえば、最大レート秒数を 60 秒、レート制限を 5 に設定した場合、60 秒ごとに 5 リクエストを許可することになります。

ユーザーレート制限

クライアントまたはユーザーレート制限は、個々のユーザーとエンドポイントごとに 1 つのカウンターを適用します。エンドポイントに接続している単一のユーザーが client-max-rate を超えると、MetaMCP はステータスコード 429 Too Many Requests で接続を拒否し始めます。

ユーザーレート制限のオプション

• Client Max Rate: 任意の時間間隔（Client Max Rate Seconds）内に、個々のユーザー（ユーザークォータ）ごとにトークンバケットに追加するトークン数。バケット内の残りトークンは、特定のユーザーが実行できるリクエスト数です。

• Client Max Rate Seconds: 最大レートが動作する時間（秒単位）。たとえば、間隔を 60 秒、レートを 5 に設定した場合、60 秒ごとに 5 リクエストを許可することになります。

• Client Max Rate Strategy: クライアントカウンターを設定するために使用する戦略を設定します。制限がクライアントの IP アドレスに適用される場合は ip を選択し、ユーザーを一意に識別するヘッダーがある場合は header に設定します。そのヘッダーは key エントリで定義する必要があります。

• Client Max Rate Strategy Key: ユーザー識別情報を含むヘッダー名です（例: トークンの Authorization、IP の X-Original-Forwarded-For）。

🔗 OpenID Connect（OIDC）プロバイダーサポート

MetaMCP は、エンタープライズ SSO 統合のための OpenID Connect 認証 をサポートしています。これにより、組織は既存のアイデンティティプロバイダー（Auth0、Keycloak、Azure AD など）を認証に使用できます。

🛠️ 設定

次の環境変数を .env ファイルに追加します:

# Required
OIDC_CLIENT_ID=your-oidc-client-id
OIDC_CLIENT_SECRET=your-oidc-client-secret
OIDC_DISCOVERY_URL=https://your-provider.com/.well-known/openid-configuration

# Optional customization
OIDC_PROVIDER_ID=oidc
OIDC_SCOPES=openid email profile
OIDC_PKCE=true

🏢 サポートされているプロバイダー

MetaMCP は一般的な OIDC プロバイダーでテストされています:

• Auth0: https://your-domain.auth0.com/.well-known/openid-configuration

• Keycloak: https://your-keycloak.com/realms/your-realm/.well-known/openid-configuration

• Azure AD: https://login.microsoftonline.com/your-tenant-id/v2.0/.well-known/openid-configuration

• Google: https://accounts.google.com/.well-known/openid-configuration

• Okta: https://your-domain.okta.com/.well-known/openid-configuration

🔒 セキュリティ機能

• 🔐 PKCE（Proof Key for Code Exchange） がデフォルトで有効

• 🛡️ Authorization Code Flow と自動ユーザー作成

• 🔄 OIDC エンドポイントの 自動検出

• 🍪 既存の認証システムとの シームレスなセッション管理

📱 使用方法

設定が完了すると、ユーザーはログインページでメール/パスワードフォームとともに "Sign in with OIDC" ボタンを表示します。認証フローは初回ログイン時に新しいユーザーを自動的に作成します。

より詳細な設定例とトラブルシューティングについては、CONTRIBUTING.md を参照してください。

⚙️ 登録制御

MetaMCP は、異なる登録方法に対して 個別の制御 を提供し、管理者がエンタープライズ展開のユーザーアクセスポリシーを細かく調整できるようにします。

🎛️ 利用可能な制御

• UI 登録: ユーザーが登録フォームを介してアカウントを作成できるかどうかを制御します

• SSO 登録: ユーザーが SSO/OAuth プロバイダー（OIDC など）を介してアカウントを作成できるかどうかを制御します

🏢 エンタープライズのユースケース

この分離により、一般的なエンタープライズシナリオが可能になります:

• UI 登録をブロック、SSO を許可: 手動サインアップを防ぎながら、企業 SSO ユーザーを許可します

• SSO 登録をブロック、UI を許可: SSO アクセスを制限しながら、手動サインアップを許可します

• 両方ブロック: 新規ユーザー登録を完全に無効にします

• 両方許可: オープンな展開のデフォルト動作

🛠️ 設定

これらの制御を設定するには、MetaMCP 管理インターフェースの Settings ページにアクセスします:

1. Settings → Authentication Settings に移動します

2. "Disable UI Registration" を切り替えて、フォームベースのサインアップを制御します

3. "Disable SSO Registration" を切り替えて、OAuth/OIDC サインアップを制御します

両方の制御は独立して機能し、登録ポリシーを完全に柔軟に設定できます。

🌐 カスタムデプロイと Nginx 用 SSE 設定

オンラインサービスや VPS にデプロイする場合は、少なくとも 2GB〜4GB のメモリを備えたインスタンスが必要です。サイズが大きいほど、パフォーマンスが向上します。

MCP は長時間接続に SSE を利用するため、nginx などのリバースプロキシを使用している場合は、設定例 nginx.conf.example を参照してください。

🏗️ アーキテクチャ

• フロントエンド: Next.js

• バックエンド: Express.js と tRPC を使用し、TS SDK と内部プロキシを通じて MCP をホスト

• 認証: Better Auth

• 構造: Turborepo と Docker パブリッシングを使用したスタンドアロンモノレポ

📊 シーケンス図

注: プロンプトとリソースはツールと同様のパターンに従います。

sequenceDiagram
    participant MCPClient as MCP Client (e.g., Claude Desktop)
    participant MetaMCP as MetaMCP Server
    participant MCPServers as Installed MCP Servers

    MCPClient ->> MetaMCP: Request list tools

    loop For each listed MCP Server
        MetaMCP ->> MCPServers: Request list_tools
        MCPServers ->> MetaMCP: Return list of tools
    end

    MetaMCP ->> MetaMCP: Aggregate tool lists & apply middleware
    MetaMCP ->> MCPClient: Return aggregated list of tools

    MCPClient ->> MetaMCP: Call tool
    MetaMCP ->> MCPServers: call_tool to target MCP Server
    MCPServers ->> MetaMCP: Return tool response
    MetaMCP ->> MCPClient: Return tool response

🗺️ ロードマップ

今後の候補:

• 🔌 ヘッドレス管理 API アクセス

• 🔍 MetaMCP エンドポイントに検索ルールを動的に適用

• 🛠️ より多くのミドルウェア

• 💬 チャット/エージェントプレイグラウンド

• 🧪 MCP ツール選択最適化のためのテストと評価

• ⚡ MCP サーバーを動的に生成

🌐 i18n

README-i18n.md を参照してください

現在は en と zh のロケールがサポートされていますが、貢献を歓迎します。

🤝 コントリビューション

コントリビューションを歓迎します！詳細は CONTRIBUTING.md を参照してください。

📄 ライセンス

MIT

あなたのプロジェクトでこのコードを使用する場合は、バックリンクを付けていただけると幸いです。

🙏 クレジット

以下のコードに触発された部分があります:

• MCP Inspector

• MCP Proxy Server

コードを直接使用したわけではありませんが、以下のプロジェクトからアイデアを得ました

• https://github.com/open-webui/openapi-servers

• https://github.com/open-webui/mcpo