DaraCloud Metabase MCP

Демонстрационный MCP-сервер для аналитики синтетической IaaS-базы DaraCloud через API Metabase.

Проект создан для докладов и обучения. Все названия, сущности и данные вымышлены и не содержат информации реальной инфраструктуры.

Архитектура

Hermes / другой MCP-клиент
          |
          | Streamable HTTP + Bearer token
          v
DaraCloud Metabase MCP
          |
          | Metabase API + X-API-Key
          v
       Metabase
          |
          v
PostgreSQL / daracloud_demo

MCP-сервер не подключается к PostgreSQL напрямую и не хранит учетные данные базы данных.

Инструменты MCP

• list_tables — список таблиц демонстрационной схемы.
• describe_table — колонки и типы данных выбранной таблицы.
• run_sql — один read-only запрос SELECT или WITH ... SELECT, результат ограничивается по числу строк.

Изменяющие SQL-команды запрещены дополнительной проверкой на уровне сервера. Для полноценной защиты подключенная к Metabase учетная запись базы данных также должна оставаться read-only.

Быстрый запуск

Требования: Linux, Python 3.11+ и настроенный Metabase API key.

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
cp .env.example .env

Заполните .env, не добавляя его в Git, затем запустите:

set -a
. ./.env
set +a
.venv/bin/python src/server.py

По умолчанию сервер слушает 127.0.0.1:8000, а MCP endpoint доступен по пути /mcp.

Переменные окружения

Переменная	Назначение
METABASE_URL	Базовый URL Metabase без завершающего /
METABASE_API_KEY	API key Metabase для выполнения запросов
METABASE_DATABASE_ID	Числовой ID базы в Metabase
METABASE_SCHEMA	Разрешенная схема, по умолчанию daracloud_demo
MCP_AUTH_TOKEN	Отдельный bearer token для входящих MCP-запросов
MCP_PUBLIC_URL	Публичный HTTPS URL MCP-сервера
MCP_HOST	Локальный адрес прослушивания
MCP_PORT	Локальный порт прослушивания
QUERY_TIMEOUT_SECONDS	Таймаут запроса к Metabase
MAX_ALLOWED_ROWS	Максимально допустимый лимит результата

Развертывание

В каталоге deploy находятся примеры unit-файла systemd и конфигурации Caddy. Перед использованием замените домены и при необходимости пути.

Для Hermes пример подключения находится в examples/hermes-config.yaml.

Демонстрационные данные

Схема и дамп синтетической базы: kosovadaria/daracloud-demo.

Безопасность

• Не коммитьте .env, API keys и bearer tokens.
• Используйте разные секреты для Metabase API и входящей MCP-аутентификации.
• Публикуйте сервер только через HTTPS reverse proxy.
• Оставляйте пользователя базы данных в Metabase с правами только на чтение.
• Это учебный проект, а не универсальный SQL firewall для недоверенных пользователей.

Лицензия

MIT.