Metabase

Metabase MCP-сервер

Metabase включает встроенный сервер Model Context Protocol (MCP), который позволяет AI-клиентам подключаться напрямую к экземпляру Metabase. Он использует https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http и основан на Agent API Metabase, предоставляя инструменты для поиска, навигации, выполнения запросов, визуализации и создания/обновления контента — всё в рамках прав доступа подключающегося пользователя.

Конечная точка

MCP-сервер доступен по адресу:

https://{your-metabase.example.com}/api/metabase-mcp

Устаревший путь /api/mcp по-прежнему работает как псевдоним для существующих клиентов, но каноническим URL для объявления является /api/metabase-mcp.

Подключение клиента

Направьте любой MCP-совместимый клиент на конечную точку /api/metabase-mcp. Например, с Claude Code:

claude mcp add metabase https://{your-metabase.example.com}/api/metabase-mcp --transport streamable-http

Для Claude Desktop создайте пользовательский коннектор, используя тот же URL.

Для Cursor откройте Settings > MCP и добавьте новый сервер с типом streamable-http и URL:

https://{your-metabase.example.com}/api/metabase-mcp

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

MCP-клиенты аутентифицируются через OAuth 2.0. Metabase использует собственный встроенный OAuth-сервер — внешний провайдер не требуется.

Процесс при первом подключении:

1. Клиент обнаруживает конечные точки OAuth Metabase.
2. Клиент регистрируется в Metabase.
3. Пользователь перенаправляется в Metabase для входа и подтверждения подключения.
4. Клиент получает токен доступа, ограниченный правами пользователя в Metabase.

Сессии на основе браузера (cookie-аутентификация) также поддерживаются и получают неограниченные области действия.

Области действия (Scopes)

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

Область действия (Scope)	Предоставляет доступ к
agent:search	search
agent:resource:read	read_resource (всегда предоставляется любому аутентифицированному вызывающему; проверки прав доступа к URI происходят внутри диспетчера)
agent:query:construct	construct_query
agent:query	query
agent:query:execute	execute_query
agent:sql:construct	construct_native_query
agent:sql:execute	execute_sql
agent:question:create	create_question
agent:question:update	update_question (также включает «перемещение карточки в коллекцию» и архивирование)
agent:question:execute	execute_question
agent:metric:create	create_metric
agent:metric:update	update_metric (также включает «перемещение метрики в коллекцию» и архивирование)
agent:dashboard:create	create_dashboard
agent:dashboard:update	update_dashboard (также включает архивирование)
agent:collection:create	create_collection

Шаблоны с подстановочными знаками (например, agent:*) соответствуют любой области действия с этим префиксом.

Метаданные защищенного ресурса OAuth доступны по адресу:

/.well-known/oauth-protected-resource/api/metabase-mcp

По умолчанию наш экран согласия предоставляет доступ ко всем областям действия без возможности настройки.

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

MCP-сервер предоставляет следующие инструменты, динамически генерируемые из метаданных конечных точек Agent API:

Поиск и чтение

Инструмент	Описание
search	Поиск таблиц, метрик, карточек, дашбордов и коллекций по ключевым словам или запросам на естественном языке.
read_resource	Чтение одной или нескольких сущностей Metabase по URI metabase://. Охватывает навигацию по базам данных/схемам/таблицам/коллекциям/вопросам/дашбордам/метрикам/преобразованиям. До 5 URI за вызов.

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

Инструмент	Описание
construct_query	Построение запроса к таблице или метрике. Принимает исходный prompt пользователя, если он доступен. Возвращает непрозрачный query_handle для использования с execute_query или visualize_query.
construct_native_query	Построение нативного (сырого SQL) запроса для базы данных. Возвращает непрозрачный query_handle для передачи в create_question и его сохранения. Не выполняет SQL; нативные дескрипторы отклоняются execute_query/query (используйте execute_sql для выполнения сырого SQL).
query	Прямой запрос к таблице или метрике. Поддерживает постраничную навигацию с помощью токенов продолжения.
execute_query	Выполнение ранее построенного запроса и возврат результатов с метаданными столбцов.
execute_sql	Выполнение сырого SQL-запроса к базе данных. Требует наличия у пользователя разрешения на нативные запросы к целевой базе данных. Может быть отключено на уровне экземпляра с помощью настройки mcp-execute-sql-enabled.
execute_question	Запуск сохраненного вопроса по ID и возврат его строк + метаданных столбцов. Выполняется с правами вызывающего. Параметризованные вопросы не поддерживаются (возвращается ошибка).

Запись

Инструмент	Описание
create_metric	Сохранение запроса как переиспользуемой метрики. Принимает query_handle из construct_query. Запрос должен содержать одну агрегацию и не более одной группировки по дате.
update_metric	Обновление сохраненной метрики. Семантика частичного обновления (patch). Установка collection_id перемещает её; установка archived: true архивирует её — обратимое мягкое удаление, используемое при запросе на удаление метрики. Заменяющий query по-прежнему должен быть валидной метрикой.
create_question	Сохранение запроса как именованного вопроса (карточки). Принимает query_handle из construct_query (MBQL) или construct_native_query (нативный SQL). Для сохранения нативного запроса требуется разрешение на нативные запросы к БД.
update_question	Обновление сохраненного вопроса. Семантика частичного обновления (patch). Установка collection_id перемещает карточку. Установка archived: true архивирует её — обратимое мягкое удаление, используемое при запросе на удаление вопроса. Замена запроса принимает дескриптор construct_query или construct_native_query.
create_dashboard	Создание нового дашборда, опционально заполненного сохраненными вопросами (автоматически размещенными на сетке).
update_dashboard	Обновление метаданных дашборда (имя, описание, коллекция, архивирование — обратимое мягкое удаление, используемое при запросе на удаление дашборда).
create_collection	Создание новой коллекции. Опционально вложенной в parent_collection_id.

Результаты запросов ограничены 200 строками на запрос. Если доступно больше строк, ответ включает continuation_token, который можно передать обратно для получения следующей страницы.

Ответы списка read_resource ограничены 25 элементами с сигналами truncated / total; для просмотра большего количества перейдите к конкретным URI или уточните запрос через search.

Ресурсы

Сервер предоставляет MCP ресурсы, чтобы клиенты могли получать дополнительный контент по URI, не перегружая описания инструментов.

URI ресурса	Описание
metabase://docs/construct-query.md	Синтаксис программ для construct_query и query: источники, операции, формы операторов, примеры работы, подводные камни.

Инструмент read_resource (см. выше) использует отдельную схему URI для навигации по сущностям Metabase (metabase://question/{id}, metabase://database/{id}/tables и т. д.). Эти два пространства имен URI независимы: metabase://docs/... предназначен для статического справочного контента, получаемого через MCP resources/read, в то время как metabase://table/... и подобные являются URI сущностей, передаваемыми в инструмент read_resource.

Поддерживаемые методы JSON-RPC

Метод	Описание
initialize	Инициализация MCP-соединения. Возвращает возможности сервера и идентификатор сессии.
notifications/initialized	Уведомление клиента о завершении инициализации.
tools/list	Список доступных инструментов (отфильтрованный по областям действия токена).
tools/call	Вызов инструмента с аргументами.
resources/list	Список доступных ресурсов (отфильтрованный по областям действия токена).
resources/read	Чтение ресурса по URI. Требует инициализированной сессии.
ping	Проверка связи (keepalive ping).

Запросы могут отправляться по отдельности или в виде пакета JSON-RPC. Сервер отвечает в формате JSON или SSE в зависимости от заголовка Accept.

Архитектура

Реализация находится в следующих файлах:

• api.clj - HTTP-обработчик. Разбирает запросы JSON-RPC, проверяет заголовки аутентификации и сессии, выполняет проверки источника (защита от DNS rebinding) и направляет вызов соответствующему методу. Поддерживает форматы ответов JSON и SSE.

• tools.clj - Диспетчеризация инструментов и генерация манифеста. Строит список инструментов из метаданных конечных точек Agent API, проверяет области действия и направляет вызовы инструментов через синтетические запросы Agent API.

• resources.clj - Реестр и обработчики ресурсов MCP. Содержит ресурсы документации (например, справочник construct_query), индексированные по URI, с контролем доступа на основе областей действия для resources/list и resources/read.

• scope.clj — Логика сопоставления областей. Поддерживает точные совпадения, шаблоны с подстановочными знаками и метку ::unrestricted для аутентификации на основе сессии.

Поток запросов

MCP client
  -> POST /api/metabase-mcp (JSON-RPC)
  -> Origin + session validation
  -> Auth: OAuth bearer token or browser session
  -> Scope check against requested tool
  -> Synthetic request to Agent API endpoint
  -> Response materialized as MCP content
  -> JSON or SSE back to client

Дополнительная информация

• Пользовательская документация MCP
• Исходный код Agent API
• Спецификация Model Context Protocol