🚀 MetaMCP (MCP-агрегатор, оркестратор, мидлвар и шлюз на docker)

📢 Последнее обновление: Эта ветка ai-dev будет активной развивающейся веткой, содержащей изменения ИИ-агентов. Пожалуйста, протестируйте прежде, чем собирать образ на основе этой ветки. Благодаря сообществу было много пулов реквестов, но их слияние и рецензирование также становится всё большим усилием. Я решил добавить изменения ИИ. По крайней мере до сих пор основной функционал работает. Также существует поддерживаемое сообществом форк (огромное спасибо!): https://github.com/Umbrella-IT-Group/metamcp

📢 Обновление: [От автора: извините за недавнюю задержку с обслуживанием, но я по крайней мере буду продолжать объединять PR, подробнее здесь]

MetaMCP — это MCP-прокси, который позволяет вам динамически агрегировать MCP-серверы в один MCP-сервер и применять промежуточные ПО. МеtaMCP сам является MCP-сервером, поэтому его можно легко встроить в ЛЮБЫЕ MCP-клиенты.

Для получения более информации посетите наш сайт документации: https://docs.metamcp.com

English | 简体中文

📋 Содержание

• 🎯 Сценарии использования

• 📖 Концепции

  • 🖥️ MCP-сервер

    • 🔐 Переменные окружения и секреты (STDIO MCP серверы)

  • 🏷️ Пространство имён MetaMCP

  • 🌐 Эндпоинт MetaMCP

  • ⚙️ Middleware

  • 🔍 Инспектор

  • ✏️ Переопределения инструментов и аннотации

• 🚀 Быстрый старт

  • 🐳 Запуск через Docker Compose (рекомендуется)

  • 📦 Среда разработки с Dev Containers (VSCode/Cursor)

  • 💻 Локальная разработка

• 🔌 Совместимость с MCP-протоколом

• 🔗 Подключение к MetaMCP

  • 📝 Например, Cursor через mcp.json

  • 🖥️ Подключение Claude Desktop и других клиентов с STDIO

  • 🔧 Устранение неполадок аутентификации по API-ключ

• ❄️ Проблема холодного запуска и настройка Dockerfile

• 🧾 Уровни журналирования

• 🔐 Аутентификация

• 🚦 Управление трафиком

  • 🚧 Ограничения скорости MCP

• 🔗 Поддержка провайдеров OpenID Connect (OIDC)

  • 🛠️ Конфигурация

  • 🏢 Поддерживаемые провайдеры

  • 🔒 Функции безопасности

  • 📱 Использование

• ⚙️ Контроль регистрации

  • 🎛️ Доступные элементы управления

  • 🏢 Корпоративные сценарии использования

  • 🛠️ Конфигурация

• 🌐 Собственное развёртывание и SSE-конфигурация для Nginx

• 🏗️ Архитектура

  • 📊 Диаграмма последовательности

• 🗺️ Roadmap

• 🌐 i18n

• 🤝 Участие

• 📄 Лицензия

• 🙏 Благодарности

Related MCP server: Master MCP Server

🎯 Сценарии использования

• 🏷️ Группируйте MCP-серверы в пространства имён, размещайте их как метая MCP и назначайте публичные эндпоинты (SSE или Streamable HTTP), с аутентификация. Одним кликом переключайте пространство для эндпоинта.

• 🎯 Выбирайте только нужные инструменты при ремиксе MCP-серверов. Применяйте другие подключаемые мидлвары для наблюдаемости, совместности, безопасность и т.д. (работа уже ведётся)

• 🔍 Используйте в качестве улучшенного MCP-инспектора с сохранёнными конфигурациями серверов и проверяйте свои MetaMCP эндпоинты локально, видите ли они работают.

• 🔍 Используйте как Elasticsearch для выбора MCP-инструментов (скоро)

Обычно разработчики могут использовать MetaMCP как инфраструктуру, чтобы размещать динамически создаваемые MCP-серверы через один эндпоинт и строить поверх него а전ентов.

Видео быстрой демонстрации: https://youtu.be/Cf6jVd2saAs

📖 Концепции

🖥️ MCP-сервер

Конфигурация MCP-сервера, которая tells MetaMCP, как запустить MCP-сервер.

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

🔐 Переменные окружения и секреты (STDIO MCP серверы)

Для STDIO MCP-серверов MetaMCP поддерживает три способа обработки переменных окружения и секретов:

**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, чтобы они были переданы процессам разработки. Это не обязательно для рабочего развертывания Docker.

🏷️ Пространство имён MetaMCP

• Группируйте один или несколько MCP-серверов в пространство имён

• Включайте/выклюйте MCP-серверы или на уровне инструментов

• Применяйте мидлвары к MCP-запросам и ответам

• Переопределяйте имена/заголовки/описания инструментов только для пространства имён и добавляйте кастомные MCP-аннотации (proc, для the for program: { "annotations": { "readOnlyHint": false } })

🌐 Эндпоинт MetaMCP

• Создавайте эндпоинты и назначайте на них пространства имён

• Несколько MCP-серверов в пространстве имён будут объединены и прocoчены как одна точка доступа MetaMCP

• Выбор между аутентификацией через API-ключ (в заголовке или параметре запроса) или стандартный OAuth согласно MCP Spec 2025-06-18

• Доступ через SSE или Streamable HTTP транспорта в MCP и OpenAPI эндпоинты для таких клиентств, как Open WebUI

⚙️ Middleware

• Перехват и трансформация MCP-запросов и ответов на уровне пространства имён

• Задачный пример: "Фильтрация неактивных инструментов" — оптимизирует контекст инструментов для LLM

• Будущие идеи: логирование инструментов, трейсы ошибок, валидация, сканирование

🔍 Инспектор

Похож на официальный MCP-инспектор, но с сохранёнными конфигурациями серверов — MetaMCP автоматически создает конфигурации, чтобы вы могли немедленно отлаживать эндпоинты MetaMCP.

✏️ Переопределение инструментов и аннотации

• Откройте пространство имён → вкладку Tools, чтобы увидеть каждый инструмент, который появляется от подключенных MCP-серверов.

• Сохранённый инструмент можно развернуть и отредактировать: изменить отображаемое имя/заголовок/описание или добавить JSON-блок аннотаций (например { "annotations": { "readOnlyHint": false } }).

• Бейджи в таблице ("overridden", "annotations" ) показывают, какие инструменты имеют нестандартные метаданные. Проведите мышкой, чтобы увидеть подсказку с описанием переопределений.

• Переопределения аннотаций объединяются с тем, что вернул вышестоящий MCP-сервер, поэтому вы можете безопасно добавлять собственные подсказки интерфейса без потери метаданных провайдера.

🚀 Быстрый старт

🐳 Запуск через Docker Compose (рекомендуется)

Клонируйте репозиторий, подготовьте .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_URA, убедитесь, что доступ только по APP_URL, потому что MetaMCP накладывает политику CORS на этот URL и другие URL не будут доступны.

Данные SQLite хранятся в томе Compose (sqlite_data). Переименуйте том в docker-compose.yml, если он конфликтует с другим проект.

🐳 Создание среды разработки с 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. При создании контейнер копирует .env со значениями по умолчанию example.env в .env.local, затем устанавливает зависимости и миграции SQLite файла.

VSCode откроет проект Dev Containers в новом окне, где по Dockerfile будет построено окружение и установлены инструменты до запуска всех зависимостей MetaMCP.

Note Этот процесс требует надежной сети, он обращается к Docker Hub, GitHub и некоторым другим сайтам. Вам стоит обеспечить сет страны, иначе сборка контейнера может завершиться неудачей.

Подождите несколько минут: в зависимости от интернета или производительности компьютера, может занять от нескольких минут до десятка минут. Вы можете кликнуть на прогресс-баре в правом нижнем углу, чтобы открыть живой журнал и проверить возможные зависания.

После завершения можно запустить pnpm dev для запуска сервера разработки.

💻 Локальная разработка

SQLite автоматически создается в data/metamcp.db (если не задана переменная окружения DATABASE;) относительно рабочей директории бэкенда.

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

🔌 Совместимость с протоколом MCP

• ✅ Поддерживаются Tools, Resources и Prompts

• ✅ MCP-серверы с поддержкой OAuth протестированы для версии от 26-03

Если у вас есть вопросы, не стесняйтесь оставлять GitHub issues или PR.

🔗 Подключение к MetaMCP

📝 Например, Cursor через mcp.json

Пример 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 и не работает с аутентификацией по API-ключу MetaMCP. По результатам тестирования рекомендуемым решением является mcp-proxy.

Вот рабочая конфигурация для Claude Desktop с использованием mcp-proxy:

Использование 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> на ваш API-ключ MetaMCP (формат: sk_mt_...)

Более подробную информацию и альтернативные подходы см. в issue #76.

🔧 Устранение неполадок с аутентификацией по API-ключу

• Аутентификация по API-ключу через параметр ?api_key= не работает для SSE. Она работает только для Streamable HTTP и OpenAPI.

• Рекомендуется использовать API-ключ в заголовке Authorization: Bearer <API_KEY>.

• При возникновении проблем с подключением попробуйте временно отключить аутентификацию, чтобы проверить, связана ли проблема с ней.

❄️ Проблема холодного старта и пользовательский 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)

• 🍪 Сеансовые cookie обеспечивают безопасные внутренние прокси-подключения MCP

• 🔑 Аутентификация по API-ключу для внешнего доступа через заголовок Authorization: Bearer <api-key>

• 🪪 MCP OAuth: у открытых конечных точек есть возможность использовать стандартный OAuth из спецификации MCP 2025-06-18, что упрощает подключение.

• 🏢 Мультитенантность: спроектирована для развёртывания организациями на собственных машинах. Поддерживает как частные, так и публичные области доступа. Пользователи могут создавать MCP, пространства имён, конечные точки и API-ключи для себя или для всех. Публичные API-ключи не могут получить доступ к частным MetaMCP.

• ⚙️ Раздельное управление регистрацией: администраторы могут независимо управлять регистрацией через интерфейс и регистрацией через SSO/OAuth на странице настроек, что позволяет гибко настраивать сценарии корпоративного развёртывания.

🚦 Управление трафиком

🚧 Ограничение скорости MCP

Функция ограничения скорости MCP позволяет задать максимальное количество запросов, которое инструмент MCP (конечная точка) будет принимать за заданный промежуток времени. Существуют две разные стратегии установки лимитов, которые можно использовать по отдельности или вместе:

• Ограничение скорости конечной точки (Rate Limiting): применяется одновременно ко всем клиентам, использующим конечную точку, с общим счётчиком.

• Ограничение скорости пользователя (Client Rate Limiting): устанавливает отдельный счётчик для каждого пользователя.

Оба типа могут сосуществовать и дополнять друг друга; счётчики хранятся в памяти. В кластере каждая машина видит и подсчитывает только проходящий через неё трафик.

Ограничение скорости конечной точки

Ограничение скорости конечной точки действует на количество одновременных транзакций, которые может обработать конечная точка. Такой тип лимита защищает сервис для всех клиентов. Когда пользователи, подключённые к конечной точке, вместе превышают rate-limiting, MetaMCP начинает отклонять подключения с кодом состояния 503 Service Unavailable.

Параметры ограничения скорости конечной точки

• Max Rate: определяет, сколько запросов вы будете принимать от всех пользователей вместе в любой момент времени. При запуске шлюза «ведро» заполнено. По мере поступления запросов от пользователей количество оставшихся токенов в «ведре» уменьшается. При этом ограничение скорости пополняет «ведро» с заданной скоростью, пока не будет достигнута максимальная ёмкость.

• Max Rate Seconds: период времени в секундах, в течение которого действуют максимальные скорости. Например, если задать max rate seconds равным 60 с, а rate-limiting равным 5, вы разрешаете 5 запросов каждые шестьдесят секунд.

Ограничение скорости пользователя

Ограничение скорости клиента или пользователя применяет один счётчик к каждому отдельному пользователю и конечной точке. Когда один пользователь, подключённый к конечной точке, превышает свой client-max-rate, MetaMCP начинает отклонять подключения с кодом состояния 429 Too Many Requests.

Параметры ограничения скорости пользователя

• Client Max Rate: количество токенов, добавляемых в «ведро» токенов для каждого отдельного пользователя (квота пользователя) за выбранный интервал времени (Client Max Rate Seconds). Оставшиеся токены в «ведре» — это количество запросов, которые может выполнить конкретный пользователь.

• Client Max Rate Seconds: период времени в секундах, в течение которого действуют максимальные скорости. Например, если задать every равным 60 с, а rate равным 5, вы разрешаете 5 запросов каждые шестьдесят секунд.

• Client Max Rate Strategy: задаёт стратегию установки счётчиков клиентов. Выберите ip, если ограничения применяются к IP-адресу клиента, или установите header, если есть заголовок, однозначно идентифицирующий пользователя. Этот заголовок должен быть определён в поле key.

• Client Max Rate Strategy Key: имя заголовка, содержащего идентификацию пользователя (например, Authorization для токенов или X-Original-Forwarded-For для IP-адресов).

🔗 Поддержка провайдеров OpenID Connect (OIDC)

MetaMCP поддерживает аутентификацию OpenID Connect для корпоративной интеграции SSO. Это позволяет организациям использовать свои существующие поставщики удостоверений (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) включён по умолчанию

• 🛡️ Поток авторизационного кода с автоматическим созданием пользователя

• 🔄 Автообнаружение конечных точек OIDC

• 🍪 Бесшовное управление сеансами с существующей системой аутентификации

📱 Использование

После настройки пользователи увидят кнопку «Sign in with OIDC» на странице входа рядом с формой электронной почты/пароля. Поток аутентификации автоматически создаёт новых пользователей при первом входе.

Более подробные примеры конфигурации и устранение неполадок см. в CONTRIBUTING.md.

⚙️ Управление регистрацией

MetaMCP предоставляет раздельное управление для разных способов регистрации, что позволяет администраторам точно настраивать политики доступа пользователей для корпоративных развёртываний.

🎛️ Доступные элементы управления

• Регистрация через интерфейс: управляет тем, могут ли пользователи создавать учётные записи через форму регистрации

• Регистрация через SSO: управляет тем, могут ли пользователи создавать учётные записи через провайдеров SSO/OAuth (OIDC и т. д.)

🏢 Корпоративные сценарии использования

Такое разделение обеспечивает распространённые корпоративные сценарии:

• Заблокировать регистрацию через интерфейс, разрешить SSO: предотвратить ручную регистрацию, разрешив при этом корпоративным пользователям SSO

• Заблокировать регистрацию через SSO, разрешить интерфейс: разрешить ручную регистрацию, ограничив доступ через SSO

• Заблокировать оба: полностью отключить регистрацию новых пользователей

• Разрешить оба: поведение по умолчанию для открытых развёртываний

🛠️ Конфигурация

Откройте страницу Settings в интерфейсе администратора MetaMCP, чтобы настроить эти элементы управления:

1. Перейдите в Settings → Authentication Settings

2. Переключите «Disable UI Registration», чтобы управлять регистрацией через форму

3. Переключите «Disable SSO Registration», чтобы управлять регистрацией через OAuth/OIDC

Оба элемента управления работают независимо, что даёт вам полную гибкость в выборе политики регистрации.

🌐 Пользовательское развёртывание и конфигурация SSE для Nginx

Если вы хотите развернуть сервис в интернете или на VPS, потребуется экземпляр с объёмом памяти не менее 2–4 ГБ. Чем больше объём, тем выше производительность.

Поскольку MCP использует SSE для длительных подключений, при использовании обратного прокси, такого как nginx, обратитесь к примеру настройки nginx.conf.example

🏗️ Архитектура

• Фронтенд: Next.js

• Бэкенд: Express.js с tRPC, размещение MCP через TS SDK и внутренний прокси

• Аутентификация: Better Auth

• Структура: автономный монорепозиторий с Turborepo и публикацией через Docker

📊 Диаграмма последовательности

Примечание: Prompts и resources следуют схожим с tools шаблонам.

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

🗺️ Дорожная карта

Возможные следующие шаги:

• 🔌 Безголовый доступ к Admin 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