Readme: Metabase MCP Server

Полнофункциональный сервер Model Context Protocol (MCP) для интеграции с Metabase, предоставляющий ИИ-ассистентам полный доступ к аналитической платформе Metabase.

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

# Install and run with npx
export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key
npx @cognitionai/metabase-mcp-server

Related MCP server: Metabase MCP Server

✨ Возможности

🎯 81+ доступных инструментов - полное покрытие Metabase API

• 📊 Управление дашбордами (23 инструмента) - полный набор CRUD-операций, управление карточками, публикация, встраивание

• 📈 Управление карточками/вопросами (21 инструмент) - выполнение запросов, обработка параметров, pivot-запросы, публичные ссылки

• 🗄️ Управление базами данных (13 инструментов) - управление подключениями, синхронизация схем, выполнение запросов

• 📋 Управление таблицами (16 инструментов) - операции с метаданными, управление полями, операции с данными

• 🔍 Дополнительные инструменты (9 инструментов) - коллекции, поиск, пользователи, отслеживание активности, ссылки на Playground

📦 Установка

💡 Рекомендуется: Node.js 20.19.0+ и npm 8.0.0+ для оптимальной совместимости

Способ 1: NPX (рекомендуется)

npx @cognitionai/metabase-mcp-server

Способ 2: Глобальная установка

npm install -g @cognitionai/metabase-mcp-server
metabase-mcp-server

Способ 3: Docker

docker run -it --rm \
  -e METABASE_URL=https://your-metabase-instance.com \
  -e METABASE_API_KEY=your_metabase_api_key \
  ghcr.io/CognitionAI/metabase-mcp-server

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

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

Аутентификация по API-ключу (предпочтительно):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_API_KEY=your_metabase_api_key

Аутентификация по имени пользователя и паролю (запасной вариант):

export METABASE_URL=https://your-metabase-instance.com
export METABASE_USERNAME=your_username
export METABASE_PASSWORD=your_password

Необязательные аргументы

Сервер поддерживает аргументы командной строки для настройки загрузки инструментов:

• --essential (по умолчанию): загружать только основные инструменты

• --all: загружать все 80+ доступных инструментов

• --write: загружать только инструменты записи/изменения

• --read: загружать только инструменты чтения

# Using published package (recommended)
# Default behavior (essential tools only)
npx @cognitionai/metabase-mcp-server

# Load all tools
npx @cognitionai/metabase-mcp-server --all

# Load only write tools
npx @cognitionai/metabase-mcp-server --write

# Load only read-only tools
npx @cognitionai/metabase-mcp-server --read

# Using local development build
npm run build
node dist/server.js                    # Default (essential tools)
node dist/server.js --all             # All tools
node dist/server.js --write           # Write tools only
node dist/server.js --read            # Read-only tools only

🔌 Примеры интеграции

Claude Desktop

Добавьте в конфигурацию Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json на macOS):

Использование опубликованного пакета:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Использование локальной сборочной версии:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

С пользовательскими флагами:

{
  "mcpServers": {
    "metabase-all": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--all"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Windsurf IDE

Добавьте в MCP-конфигурацию Windsurf (~/.windsurf/mcp_config.json):

Использование опубликованного пакета:

{
  "mcpServers": {
    "metabase": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

Использование локальной сборочной версии:

{
  "mcpServers": {
    "metabase": {
      "command": "node",
      "args": ["/path/to/metabase-mcp-server/dist/server.js"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

С пользовательскими флагами:

{
  "mcpServers": {
    "metabase-read": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--read"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    },
    "metabase-write": {
      "command": "npx",
      "args": ["@cognitionai/metabase-mcp-server", "--write"],
      "env": {
        "METABASE_URL": "https://your-metabase-instance.com",
        "METABASE_API_KEY": "your_metabase_api_key"
      }
    }
  }
}

🛠️ Доступные инструменты

Основные операции

• list_dashboards - список всех дашбордов

• get_dashboard - получить дашборд по ID

• create_dashboard - создать новый дашборд

• update_dashboard - обновить существующий дашборд

• delete_dashboard - удалить дашборд

• copy_dashboard - копировать дашборд

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

• get_dashboard_cards - получить все карточки дашборда

• add_card_to_dashboard - добавить карточку на дашборд

• remove_card_from_dashboard - удалить карточку с дашборда

• update_dashboard_card - обновить положение/настройки карточки

• execute_dashboard_card - выполнить конкретную карточку дашборда

Публикация и встраивание

• create_public_link - создать публичную ссылку на дашборд

• delete_public_link - удалить публичную ссылку на дашборд

• list_public_dashboards - список публичных дашбордов

• list_embeddable_dashboards - список встраиваемых дашбордов

Параметры и запросы

• get_dashboard_param_values - получить значения параметров

• search_dashboard_param_values - искать значения параметров

• get_dashboard_param_remapping - получить переназначение параметров

• execute_dashboard_query - выполнить запросы дашборда

Расширенные возможности

• get_dashboard_related - получить связанный контент

• get_dashboard_query_metadata - получить метаданные запроса

• update_dashboard_cards - массовое обновление карточек

• save_dashboard - сохранить изменения дашборда

• get_dashboard_items - получить элементы дашборда

Основные операции

• list_cards - список всех карточек/вопросов

• get_card - получить карточку по ID

• create_card - создать новую карточку

• update_card - обновить существующую карточку

• delete_card - удалить карточку

• copy_card - копировать карточку

Выполнение запросов

• execute_card - выполнить запрос карточки

• execute_card_query_with_format - выполнить в указанном формате

• execute_pivot_card_query - выполнить pivot-запрос

• get_card_query_metadata - получить метаданные запроса

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

• move_cards - переместить карточки между коллекциями

• move_cards_to_collection - массовое перемещение в коллекцию

• get_card_dashboards - получить дашборды, содержащие карточку

• get_card_series - получить данные серии карточки

Параметры и значения

• get_card_param_values - получить значения параметров

• search_card_param_values - искать значения параметров

• get_card_param_remapping - получить переназначение параметров

Публикация

• create_card_public_link - создать публичную ссылку на карточку

• delete_card_public_link - удалить публичную ссылку на карточку

• get_public_cards - список публичных карточек

• get_embeddable_cards - список встраиваемых карточек

Основные операции

• list_databases - список всех баз данных

• get_database - получить сведения о базе данных

• create_database - создать подключение к базе данных

• update_database - обновить настройки базы данных

• delete_database - удалить подключение к базе данных

Схема и метаданные

• get_database_schema_tables - получить таблицы базы данных

• get_database_schemas - получить схемы базы данных

• get_database_metadata - получить полные метаданные

• sync_database_schema - синхронизировать метаданные схемы

Операции с запросами

• execute_query - выполнить SQL-запросы

• execute_query_export - выполнить и экспортировать результаты

Обслуживание

• get_database_usage_info - получить статистику использования

• rescan_database_field_values - повторно просканировать значения полей

Основные операции

• list_tables - список таблиц с фильтрацией

• get_table - получить сведения о таблице

• update_table - обновить конфигурацию таблицы

• update_tables - массовое обновление таблиц

Операции с данными

• get_table_data - получить данные таблицы

• append_csv_to_table - добавить данные из CSV

• replace_table_csv - заменить данными из CSV

Схема и связи

• get_table_query_metadata - получить метаданные запроса

• get_table_fks - получить связи внешних ключей

• get_table_related - получить связанные таблицы

• sync_table_schema - синхронизировать схему таблицы

Управление полями

• reorder_table_fields - изменить порядок отображения полей

• rescan_table_field_values - повторно просканировать значения полей

• discard_table_field_values - сбросить кэшированные значения

Интеграция с карточками

• get_card_table_fks - получить внешние ключи таблицы карточки

• get_card_table_query_metadata - получить метаданные таблицы карточки

Коллекции

• list_collections - список всех коллекций

• create_collection - создать новую коллекцию

• update_collection - обновить коллекцию

• delete_collection - удалить коллекцию

• get_collection_items - получить элементы коллекции

Поиск и обнаружение

• search_content - искать по всему контенту

Активность и аналитика

• get_recent_views - получить недавнюю активность

• get_popular_items - получить популярный контент

Ссылки на Playground

• get_metabase_playground_link - сгенерировать интерактивные ссылки на Playground

🧪 Разработка

Настройка

git clone https://github.com/CognitionAI/metabase-mcp-server.git
cd metabase-mcp-server
npm install

Сборка

npm run build

Режим разработки

npm run watch

Отладка

Используйте MCP Inspector для отладки:

npm run inspector

🔍 Проверка аутентификации

Аутентификация по API-ключу

1. Установите METABASE_URL и METABASE_API_KEY

2. Запустите сервер и убедитесь, что в журнале указано "Using Metabase API Key"

3. Проверьте с помощью инструмента list_dashboards

Аутентификация по имени пользователя и паролю

1. Удалите переменную METABASE_API_KEY

2. Установите METABASE_URL, METABASE_USERNAME, METABASE_PASSWORD

3. Запустите сервер и убедитесь, что в журнале указано "Using username/password"

4. Проверьте с помощью инструмента list_dashboards

🐛 Устранение неполадок

Частые проблемы

Ошибки аутентификации:

• Убедитесь, что URL Metabase доступен

• Проверьте действительность API-ключа в настройках администратора Metabase

• Убедитесь, что имя пользователя и пароль указаны верно

Проблемы с подключением:

• Подтвердите, что экземпляр Metabase запущен

• Проверьте сетевое подключение

• Проверьте SSL-сертификаты при использовании HTTPS

Ошибки выполнения инструментов:

• Проверьте разрешения Metabase для вашего пользователя/API-ключа

• Убедитесь, что запрашиваемый ресурс существует

• Просмотрите журналы сервера, чтобы получить подробные сообщения об ошибках

📄 Лицензия

Этот проект распространяется под лицензией MIT - подробности в файле LICENSE.

🤝 Вклад в проект

Вклад приветствуется! Посетите наш GitHub-репозиторий, чтобы:

• 🐛 Сообщать об ошибках

• 💡 Предлагать новые возможности

• 🔧 Отправлять пул-реквесты

• 📖 Улучшать документацию

Рекомендации по разработке

1. Сделайте форк репозитория

2. Создайте feature-ветку

3. Внесите изменения с тестами

4. Убедитесь, что все тесты проходят

5. Отправьте пул-реквест

🆘 Поддержка

• 📚 Документация

• 🐛 Трекер проблем

Создано с ❤️ для всего мира