MCP-сервер обеспечивает интеграцию LLM-клиентов (ИИ-ассистентов) с Аналитическим порталом ModusBI, позволяя выполнять действия по командам на естественном языке.

MCP-сервер — это мост между ИИ-ассистентом (например, Claude Desktop, Claude Code, Cursor и другие клиенты с поддержкой MCP) и Аналитическим порталом (ModusBI). Вы пишете ассистенту обычным языком, например, фразу «собери дашборд по продажам за квартал» — сервер переводит просьбу в действия на портале. Важно: он не анализирует данные и не принимает решения за вас — только выполняет команды по созданию и изменению отчетов.

Что такое MCP и как это работает

MCP-сервер предназначен для быстрого создания и изменения отчетов на Аналитическом портале по промптам. Он умеет:

• создавать отчет, даже на основе скриншота;
• описывать датасет на SQL;
• добавлять компоненты (графики, таблицы, фильтры);
• применять стили и настройки оформления.

Основная ценность — скорость и итеративность: собрать прототип за минуту, изменить одним промптом, поэкспериментировать с типами визуализаций, layout и темами вместо ручной сборки через UI портала.

Ссылка на репозиторий

Весь код и полная документация по ModusBI MCP Server доступны в репозитории: github.com/modus-bi/mcp-modusbi.

Требования для начала работы

Для запуска сервера потребуется:

1. ИИ-клиент с поддержкой MCP, например, Claude Desktop, Cursor, а также другие клиенты, такие как Claude Code Desktop, OpenAI Desktop, Claude Code CLI, Codex CLI, VS Code с настроенной LLM, некоторые веб-версии и другие альтернативные решения.
2. Готовый бинарник MCP-сервера под вашу ОС — со страницы релизов (есть сборки под Linux x86-64, Windows x86-64 и macOS Apple Silicon).
3. Доступ к порталу ModusBI: адрес (URL), логин и пароль API-пользователя.

Ни Python, ни git не нужны. Они понадобятся только при запуске из исходников — это маршрут разработчика, для быстрого старта он лишний.

Как подключить (кратко)

Сервер запускает не человек напрямую, а MCP-клиент (например, Claude Desktop или Claude Code): клиент читает конфигурацию, поднимает процесс сервера и общается с ним по stdio. Поэтому «запуск» на практике сводится к двум вещам: подготовить окружение и описать сервер в конфигурации клиента.

Ниже приведены два варианта подключения: автоматическая через ассистента или ручная. Выберите тот, который удобнее. Подробная инструкция по подключению – в разделе docs/start/.

Вариант А. Автоматическая настройка через ассистента

Если ваш ИИ-клиент умеет редактировать файлы и запускать команды (например, Claude Code или Cursor с доступом к терминалу), вы можете поручить настройку самому ассистенту. Просто дайте ему ссылку на подробную инструкцию по подключению из репозитория и попросите выполнить установку MCP-сервера. Ассистент прочитает документацию, скачает бинарник, создаст конфигурационный файл с вашими учетными данными (которые вы ему сообщите) и запустит сервер. Это избавляет от ручного копирования путей и правки JSON.

Пример промпта для ассистента: «Пожалуйста, настрой мне ModusBI MCP Server, следуя официальной инструкции: https://github.com/modus-bi/mcp-modusbi/blob/master/docs/start/connect.md. Используй адрес портала https://my-portal.company.com, логин api_user и пароль ********. Хочу работать в режиме чтения-записи.»

Ассистент самостоятельно выполнит все необходимые шаги. Этот способ особенно удобен для быстрого старта и для тех, кто не хочет разбираться в структуре конфигов.

Сервер интегрируется с Аналитическим порталом через API и выполняет запрошенные действия с отчетами, датасетами и компонентами. Один процесс сервера обслуживает один портал: если нужно работать с несколькими порталами, создайте в настройках вашего ИИ-клиента отдельные конфигурации для каждого из них, указав свои адреса и учетные данные.

Вариант Б. Ручная настройка (пошагово)

Шаг 1. Установите ИИ-клиент. Подойдет любой с поддержкой MCP — например, Claude Desktop или Cursor.

Шаг 2. Скачайте сервер. Возьмите готовый бинарник под вашу ОС со страницы релизов, положите в удобный каталог (например, /usr/local/bin/modusbi-mcp-server или C:\Tools\modusbi-mcp-server.exe) и запомните абсолютный путь — он понадобится в конфиге. Устанавливать больше ничего не нужно. Альтернатива — запуск из исходников, оба способа расписаны в инструкции по установке.

Шаг 3. Опишите сервер в настройках клиента. Запускать сервер вручную не нужно: ИИ-клиент сам читает конфигурацию и поднимает его. Где лежит файл конфигурации:

Клиент	Файл конфигурации
Claude Desktop (macOS)	~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop (Windows)	%APPDATA%\Claude\claude_desktop_config.json
Cursor	.cursor/mcp.json в корне проекта
Claude Code	.mcp.json в корне проекта

 

Пример содержимого для Linux/macOS (для Windows в command укажите путь к .exe с экранированными слэшами, например C:\Tools\modusbi-mcp-server.exe). Пример содержит условные данные — вместо них укажите реальный адрес портала, логин и пароль:

{
  "mcpServers": {
    "modusbi": {
      "command": "/usr/local/bin/modusbi-mcp-server",
      "args": ["--readonly"],
      "env": {
        "MODUSBI_URL": "https://ваш-портал.example.com",
        "MODUSBI_USERNAME": "<логин>",
        "MODUSBI_PASSWORD": "<пароль>"
      }
    }
  }
}

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

Обратите внимание на флаг --readonly в args. Без флага сервер тоже работает только на чтение. Чтобы ассистент мог создавать и изменять отчеты, укажите вместо него --readwrite. Подробности — в инструкции подключения.

Шаг 4. Перезапустите ИИ-клиент, чтобы он подхватил новую конфигурацию.

Проверьте связь: спросите ассистента «Покажи список отчётов на портале». Если он вернул список — все работает.

Шаг 5. Соберите первый дашборд. Просто опишите словами, что хотите увидеть.

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

Для получения полноценных возможностей рекомендуется:

1. использовать MCP-сервер совместно с установкой файлов скиллов и агентов из репозитория;
2. использовать MCP Playwright для визуальной верификации отчетов в браузере с помощью ИИ-агентов верификации (есть в документации и скиллах);
3. использовать MCP для баз данных (PostgreSQL, ClickHouse) для управления вашими датасетами и отдельной аналитики.

Безопасность и ограничения

• По умолчанию сервер запускается в режиме только чтение (--readonly). Это предотвращает случайные изменения данных. В этом режиме доступны: получение списков и содержимого отчетов, проверки, выгрузка готовых отчетов в файлы. Любое создание, изменение или удаление заблокировано.
• Для выполнения операций создания, изменения или удаления необходимо явно указать флаг --readwrite при запуске. В этом режиме становятся доступны и необратимые операции, такие как удаление отчетов.

• Для публичных стендов и песочниц предусмотрен режим --demo — он совпадает с readonly, но дополнительно накладывает лимиты нагрузки (число операций, размер выборки, объём создаваемых сущностей).

Перед работой обязательно прочитайте DISCLAIMER.md.

Код и полная документация

Код и полная документация: github.com/modus-bi/mcp-modusbi. Руководства по ролям:

1. Пользователь — подключение готового сервера к ИИ-клиенту.
2. Аналитик — руководство описывает, как через ассистента быстро собирать и изменять дашборды, используя готовые промпты и скиллы, вместо ручной сборки через UI.
3. Разработчик — руководство содержит карту кода, рабочий цикл и инструкции по добавлению новых слагов, билдеров и инструментов.
4. Тестировщик  — руководство помогает проверять, что ассистент правильно понял запрос и что результат в браузере соответствует ожидаемому (рендер-контракт).
5. Общая карта документации — разделы: architecture (устройство сервера), start (установка, руководства, FAQ, диагностика), prompts (встроенные промпты-сценарии), skills (каталог готовых скиллов), backlog (планы развития).