Metabase MCP Server — подключите ИИ-ассистентов к вашей аналитике Metabase

Высокопроизводительный сервер протокола контекста модели (MCP) для Metabase, позволяющий ИИ-ассистентам, таким как Claude, Cursor и другим MCP-клиентам, беспрепятственно взаимодействовать с вашим экземпляром Metabase. Выполняйте запросы к базам данных, запускайте SQL, управляйте дашбордами и автоматизируйте аналитические рабочие процессы с помощью естественного языка через операции с базами данных на базе ИИ.

Идеально подходит для: аналитиков данных, разработчиков и команд, желающих интегрировать ИИ-ассистентов со своей платформой бизнес-аналитики Metabase для автоматизированных SQL-запросов, управления дашбордами и исследования данных.

Основные возможности

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

• Список баз данных: Просмотр всех настроенных баз данных Metabase

• Обнаружение таблиц: Исследование таблиц с метаданными и описаниями

• Инспекция полей: Получение подробной информации о полях/столбцах с интеллектуальной пагинацией

Запросы и аналитика

• Выполнение SQL: Запуск нативных SQL-запросов с поддержкой параметров и шаблонизацией

• Поддержка MongoDB: Выполнение нативных запросов MongoDB с автоматическим преобразованием JSON для конвейеров агрегации

• Управление карточками: Выполнение, создание и управление вопросами/карточками Metabase (SQL и MongoDB)

• Организация коллекций: Создание и управление коллекциями для лучшей организации

• Запросы на естественном языке: Позвольте ИИ-ассистентам переводить вопросы в SQL или MongoDB-запросы

Аутентификация и безопасность

• Поддержка API-ключей: Безопасная аутентификация через API-ключи Metabase (рекомендуется)

• Сессионная аутентификация: Альтернативная аутентификация по электронной почте/паролю

• Переменные окружения: Безопасное управление учетными данными через файлы .env

Интеграция с ИИ-ассистентами

• Claude Desktop: Нативная интеграция с ИИ Claude от Anthropic

• Cursor IDE: Бесшовная интеграция для разработки с помощью ИИ

• Любой MCP-клиент: Совместимость со всеми клиентами протокола контекста модели

Улучшенная производительность и надежность

• Контекстно-зависимое логирование: Логирование в реальном времени с уровнями debug, info, warning и error, доступными для ИИ-клиентов

• Правильная обработка ошибок: Исключения ToolError в FastMCP для более понятных сообщений об ошибках и отладки

• Стек промежуточного ПО: Встроенная обработка ошибок и логирование для надежности в продакшене

• Лучшие практики: Соответствие последним шаблонам FastMCP с предотвращением дублирования и чистой конфигурацией

• Современный Python: Использование подсказок типов Python 3.12+ (синтаксис |) для лучшей безопасности типов

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

Предварительные требования

• Python 3.12+

• Экземпляр Metabase с доступом к API

• Менеджер пакетов uvx или uv

Установка

Вариант 1: Использование uvx (Самый простой — установка не требуется)

# Run directly without installing (like npx for Python)
uvx metabase-mcp

# With environment variables
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

Вариант 2: Установка из PyPI

# Install globally
uv tool install metabase-mcp

# Or with pip
pip install metabase-mcp

# Then run
metabase-mcp

Вариант 3: Настройка для разработки (из исходного кода)

# Clone the repository
git clone https://github.com/cheukyin175/metabase-mcp.git
cd metabase-mcp

# Install dependencies
uv sync

# Run the server
uv run python server.py

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

Создайте файл .env с вашими учетными данными Metabase:

cp .env.example .env

Параметры конфигурации

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

METABASE_URL=https://your-metabase-instance.com
METABASE_API_KEY=your-api-key-here

Вариант 2: Аутентификация по электронной почте/паролю

METABASE_URL=https://your-metabase-instance.com
METABASE_USER_EMAIL=your-email@example.com
METABASE_PASSWORD=your-password

Опционально: Тайм-аут HTTP для API Metabase

METABASE_HTTP_TIMEOUT=30.0  # Default: 30.0 seconds

Опционально: Пользовательский хост/порт для SSE/HTTP

HOST=localhost  # Default: 0.0.0.0
PORT=9000      # Default: 8000

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

Запуск сервера

Быстрый старт (настройка не требуется)

# Run directly with uvx
uvx metabase-mcp

# With custom Metabase instance
METABASE_URL=https://your-instance.com METABASE_API_KEY=your-key uvx metabase-mcp

Из исходного кода (разработка)

# STDIO transport (default)
uv run python server.py

# SSE transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --sse

# HTTP transport (uses HOST=0.0.0.0, PORT=8000 by default)
uv run python server.py --http

# Custom host and port via environment variables
HOST=localhost PORT=9000 uv run python server.py --sse
HOST=192.168.1.100 PORT=8080 uv run python server.py --http

Интеграция с Cursor

Вы можете вручную настроить Cursor, отредактировав его настройки.

Для транспорта SSE: Вы должны запустить сервер перед использованием Cursor:

uv run python server.py --sse

Интеграция с Claude Desktop

Вариант 1: Использование uvx (рекомендуется)

Добавьте это в ~/Library/Application Support/Claude/claude_desktop_config.json:

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uvx",
            "args": ["metabase-mcp"],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Вариант 2: Использование локальной установки

Если вы клонировали репозиторий:

{
    "mcpServers": {
        "metabase-mcp": {
            "command": "uv",
            "args": [
                "run",
                "--directory",
                "/absolute/path/to/metabase-mcp",
                "python",
                "server.py"
            ],
            "env": {
                "METABASE_URL": "https://your-metabase-instance.com",
                "METABASE_API_KEY": "your-api-key-here"
            }
        }
    }
}

Вариант 3: Использование FastMCP CLI

fastmcp install server.py -n "Metabase MCP"

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

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

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

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

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

Методы транспорта

Сервер поддерживает несколько методов транспорта:

• STDIO (по умолчанию): Для интеграции с IDE (Cursor, Claude Desktop)

• SSE: Server-Sent Events для веб-приложений

• HTTP: Стандартный HTTP для доступа к API

uv run python server.py                        # STDIO (default)
uv run python server.py --sse                  # SSE (HOST=0.0.0.0, PORT=8000)
uv run python server.py --http                 # HTTP (HOST=0.0.0.0, PORT=8000)
HOST=localhost PORT=9000 uv run python server.py --sse   # Custom host/port

Разработка

Настройка среды разработки

# Install with dev dependencies
uv sync --group dev

# Or with pip
pip install -r requirements-dev.txt

Качество кода

# Run linting
uv run ruff check .

# Format code
uv run ruff format .

# Type checking
uv run mypy server.py

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

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

# List all databases
databases = await list_databases()

# Execute a SQL query
result = await execute_query(
    database_id=1,
    query="SELECT * FROM users LIMIT 10"
)

# Create and run a card
card = await create_card(
    name="Active Users Report",
    database_id=1,
    query="SELECT COUNT(*) FROM users WHERE active = true",
    collection_id=2
)

Структура проекта

metabase-mcp/
├── server.py                 # Main MCP server implementation
├── pyproject.toml           # Project configuration and dependencies
└── .env.example             # Environment variables template

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

Мы приветствуем любой вклад! Пожалуйста, не стесняйтесь отправлять Pull Request.

Лицензия

Лицензия MIT — подробности см. в файле LICENSE

Ресурсы

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

• Протокол контекста модели (MCP)

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

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

• Cursor IDE

Ключевые слова и темы

metabase mcp model-context-protocol claude cursor ai-assistant fastmcp sql database analytics business-intelligence bi data-analysis anthropic llm python automation api data-science query-builder natural-language-sql

История звезд

Если вы находите этот проект полезным, пожалуйста, поставьте ему звезду! Это помогает другим узнать об этом инструменте.

Варианты использования

• Запросы к базе данных на естественном языке: Попросите Claude сделать запрос к вашим базам данных Metabase на обычном английском языке

• Автоматизированная генерация отчетов: Используйте ИИ для создания и управления карточками и коллекциями Metabase

• Исследование данных: Позвольте ИИ-ассистентам помочь вам найти инсайты в ваших данных

• Помощь в написании SQL-запросов: Получите помощь в написании и оптимизации SQL-запросов с помощью ИИ

• Управление дашбордами: Автоматизируйте создание и организацию дашбордов Metabase

• Рабочие процессы анализа данных: Интегрируйте аналитику на базе ИИ в ваш рабочий процесс разработки