StarRocks MCP Server

официальный

Взаимодействие со StarRocks

GitHub
178

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

MseeP.ai Security Assessment Badge

Официальный MCP-сервер StarRocks

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

StarRocks Server MCP server

Возможности

  • Прямое выполнение SQL: Выполнение запросов SELECT (read_query) и команд DDL/DML (write_query).
  • Исследование баз данных: Просмотр списка баз данных и таблиц, получение схем таблиц (ресурсы starrocks://).
  • Системная информация: Доступ к внутренним метрикам и состояниям StarRocks через путь ресурса proc://.
  • Детальные обзоры: Получение исчерпывающих сводок по таблицам (table_overview) или целым базам данных (db_overview), включая определения столбцов, количество строк и образцы данных.
  • Визуализация данных: Выполнение запроса и генерация графика Plotly непосредственно из результатов (query_and_plotly_chart).
  • Интеллектуальное кэширование: Обзоры таблиц и баз данных кэшируются в памяти для ускорения повторяющихся запросов. При необходимости кэш можно обойти.
  • Гибкая конфигурация: Настройка параметров подключения и поведения через переменные окружения.

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

  • Python 3.11 или новее.
  • Доступный кластер StarRocks (сервис FE). По умолчанию сервер подключается к localhost:9030 по протоколу MySQL.
  • uv — быстрый менеджер пакетов и проектов Python (современная замена pip + virtualenv) от Astral. Этот проект использует uv для разрешения зависимостей, создания виртуального окружения и запуска сервера. Команды uv run в этом README автоматически создают изолированное окружение и устанавливают необходимые зависимости при первом использовании, поэтому ручной шаг pip install не требуется.

Установка uv

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via Homebrew / pipx / pip
brew install uv
# pipx install uv
# pip install uv

Смотрите официальное руководство по установке uv для других вариантов. После установки убедитесь, что он доступен в вашем PATH:

uv --version

Установка

Обычно вам не нужно устанавливать пакет вручную — MCP-хост запускает его за вас через uv (см. Конфигурация ниже). uv загружает пакет и его зависимости по требованию.

Для прямого запуска в целях тестирования или разработки:

# Run the published package in a throwaway environment
uv run --with mcp-server-starrocks mcp-server-starrocks --help

# Or, from a local checkout of this repository
git clone https://github.com/starrocks/mcp-server-starrocks.git
cd mcp-server-starrocks
uv sync                      # create the virtual environment and install dependencies
uv run mcp-server-starrocks --help

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

MCP-сервер обычно запускается через MCP-хост. Конфигурация передается хосту, указывая, как запустить процесс MCP-сервера StarRocks.

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

Для запуска сервера в режиме Streamable HTTP:

Сначала проверьте, что соединение со StarRocks в порядке (9030 — это порт протокола MySQL StarRocks, а не порт HTTP-сервера):

$ STARROCKS_URL=root:@localhost:9030 uv run mcp-server-starrocks --test

Запустите сервер:

uv run mcp-server-starrocks --mode streamable-http --port 8000

Затем настройте MCP следующим образом:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Использование uv с установленным пакетом (отдельные переменные окружения):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Использование uv с установленным пакетом (URL-адрес подключения):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": ["run", "--with", "mcp-server-starrocks", "mcp-server-starrocks"],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Использование uv с локальной директорией (для разработки):

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_HOST": "default localhost",
        "STARROCKS_PORT": "default 9030",
        "STARROCKS_USER": "default root",
        "STARROCKS_PASSWORD": "default empty",
        "STARROCKS_DB": "default empty"
      }
    }
  }
}

Использование uv с локальной директорией и URL-адресом подключения:

{
  "mcpServers": {
    "mcp-server-starrocks": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mcp-server-starrocks", // <-- Update this path
        "run",
        "mcp-server-starrocks"
      ],
      "env": {
        "STARROCKS_URL": "root:password@localhost:9030/my_database"
      }
    }
  }
}

Аргументы командной строки:

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

uv run mcp-server-starrocks --help
  • --mode {stdio,sse,http,streamable-http}: Режим транспорта (по умолчанию: stdio или переменная окружения MCP_TRANSPORT_MODE)
  • --host HOST: Хост сервера для режимов HTTP (по умолчанию: localhost)
  • --port PORT: Порт сервера для режимов HTTP
  • --test: Запуск в тестовом режиме для проверки функциональности

Примеры:

# Start in streamable HTTP mode on custom host/port
uv run mcp-server-starrocks --mode streamable-http --host 0.0.0.0 --port 8080

# Start in stdio mode (default)
uv run mcp-server-starrocks --mode stdio

# Run test mode
uv run mcp-server-starrocks --test
  • Поле url должно указывать на конечную точку Streamable HTTP вашего MCP-сервера (при необходимости измените хост/порт).
  • С этой конфигурацией клиенты могут взаимодействовать с сервером, используя стандартные JSON через HTTP POST запросы. Специальный SDK не требуется.
  • Все API инструментов принимают и возвращают стандартный JSON, как описано выше.

Примечание: Режим sse (Server-Sent Events) устарел и больше не поддерживается. Пожалуйста, используйте режим Streamable HTTP для всех новых интеграций.

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

Конфигурация подключения

Вы можете настроить подключение к StarRocks, используя либо отдельные переменные окружения, либо единый URL-адрес подключения:

Вариант 1: Отдельные переменные окружения

  • STARROCKS_HOST: (Необязательно) Имя хоста или IP-адрес сервиса StarRocks FE. По умолчанию localhost.
  • STARROCKS_PORT: (Необязательно) Порт протокола MySQL сервиса StarRocks FE. По умолчанию 9030.
  • STARROCKS_USER: (Необязательно) Имя пользователя StarRocks. По умолчанию root.
  • STARROCKS_PASSWORD: (Необязательно) Пароль StarRocks. По умолчанию пустая строка.
  • STARROCKS_PASSWORD_KEYCHAIN_SERVICE: (Необязательно, только macOS) Имя сервиса универсального пароля, используемое при чтении пароля из Keychain. Используется только в том случае, если явный пароль не указан через STARROCKS_PASSWORD или STARROCKS_URL.
  • STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT: (Необязательно, только macOS) Имя учетной записи универсального пароля, используемое при чтении пароля из Keychain. По умолчанию соответствует разрешенному пользователю StarRocks.
  • STARROCKS_DB: (Необязательно) База данных по умолчанию, используемая, если она не указана в аргументах инструментов или URI ресурсов. Если задано, соединение попытается выполнить USE для этой базы данных. Такие инструменты, как table_overview и db_overview, будут использовать её, если часть с базой данных опущена в их аргументах. По умолчанию пусто (нет базы данных по умолчанию).

Вариант 2: URL-адрес подключения (имеет приоритет над отдельными переменными)

  • STARROCKS_URL: (Необязательно) Строка URL-адреса подключения, содержащая все параметры подключения в одной переменной. Формат: [<schema>://]user:password@host:port/database. Часть схемы необязательна. Если эта переменная задана, она имеет приоритет над отдельными переменными STARROCKS_HOST, STARROCKS_PORT, STARROCKS_USER, STARROCKS_PASSWORD и STARROCKS_DB.

    Примеры:

Приоритет пароля:

  • Пароль, встроенный в STARROCKS_URL, имеет преимущество, включая явный пустой пароль, например user:@host:9030/db.
  • Если STARROCKS_URL не содержит пароль, используется STARROCKS_PASSWORD, если он задан.
  • Если ни один явный источник пароля не задан, а STARROCKS_PASSWORD_KEYCHAIN_SERVICE настроен, пароль считывается из macOS Keychain.

Пример для macOS Keychain

Сохраните пароль:

security add-generic-password -U -a root -s mcp-server-starrocks -w 'secret'

Проверьте сохраненный пароль:

security find-generic-password -a root -s mcp-server-starrocks -w

Используйте его с этим сервером:

export STARROCKS_URL=root@localhost:9030/test_db
export STARROCKS_PASSWORD_KEYCHAIN_SERVICE=mcp-server-starrocks
export STARROCKS_PASSWORD_KEYCHAIN_ACCOUNT=root

Дополнительная конфигурация

  • STARROCKS_FE_ARROW_FLIGHT_SQL_PORT: (Необязательно) Порт Arrow Flight SQL сервиса StarRocks FE. Если задан, сервер подключается с использованием высокопроизводительного протокола Arrow Flight SQL (через драйверы ADBC) вместо стандартного протокола MySQL. Оставьте незаданным для использования соединения MySQL по умолчанию. Хост, пользователь и пароль берутся из тех же настроек подключения, что описаны выше.

  • STARROCKS_OVERVIEW_LIMIT: (Необязательно) Приблизительный лимит символов для общего текста, генерируемого инструментами обзора (table_overview, db_overview) при извлечении данных для заполнения кэша. Это помогает предотвратить чрезмерное использование памяти для очень больших схем или многочисленных таблиц. По умолчанию 20000.

  • STARROCKS_MCP_OUTPUT_DIR: (Необязательно) Директория, используемая read_query, когда его аргумент output_file является относительным путем. По умолчанию ~/.mcp-server-starrocks/output/. Директория создается по требованию. Абсолютные пути, переданные в output_file (включая пути с префиксом ~), игнорируют эту настройку. Примечание: файлы записываются на машине, где работает MCP-сервер. Для Claude Code / Claude Desktop сервер работает локально, поэтому файлы сохраняются на вашем ноутбуке. При удаленном/HTTP развертывании файл сохраняется на сервере, а не на клиенте.

  • STARROCKS_MYSQL_AUTH_PLUGIN: (Необязательно) Указывает плагин аутентификации, используемый при подключении к сервису StarRocks FE. Например, установите значение mysql_clear_password, если ваше развертывание StarRocks требует аутентификации с открытым текстом пароля (например, при использовании определенных конфигураций LDAP или внешней аутентификации). Устанавливайте этот параметр только в том случае, если ваше окружение специально этого требует; в противном случае используется плагин аутентификации по умолчанию.

  • MCP_TRANSPORT_MODE: (Необязательно) Режим связи, определяющий, как MCP-сервер предоставляет свои сервисы. Доступные варианты:

    • stdio (по умолчанию): Взаимодействие через стандартный ввод/вывод, подходит для размещения на MCP-хосте.
    • streamable-http (Streamable HTTP): Запускается как Streamable HTTP-сервер, поддерживающий вызовы RESTful API.
    • sse: (Устарело, не рекомендуется) Запускается в режиме потоковой передачи Server-Sent Events (SSE), подходит для сценариев, требующих потоковых ответов. Примечание: Режим SSE больше не поддерживается, рекомендуется повсеместно использовать режим Streamable HTTP.

Компоненты

Инструменты

  • read_query

    • Описание: Выполнение запроса SELECT или других команд, возвращающих ResultSet (например, SHOW, DESCRIBE). При необходимости записывает полный результат в локальный файл вместо возврата его в строке — полезно для результатов, слишком больших для контекста модели.
    • Входные данные: 
      {
  "query": "SQL query string",
  "db": "database name (optional, uses default database if not specified)",
  "output_file": "optional path; if set, writes the full result to disk and returns only a summary + small preview. Relative paths resolve against STARROCKS_MCP_OUTPUT_DIR (default: ~/.mcp-server-starrocks/output/); absolute paths and ~ are used as-is",
  "output_format": "optional: csv | tsv | json | jsonl. If omitted, inferred from output_file extension (.csv/.tsv/.json/.jsonl/.ndjson); defaults to csv"
}
    • Выходные данные: Без output_file — текстовое содержимое с результатами запроса в формате, подобном CSV, со строкой заголовка и сводкой количества строк. С output_file — краткая сводка, включающая разрешенный абсолютный путь, размер в байтах и количество строк, а также небольшой предварительный просмотр. Возвращает сообщение об ошибке в случае сбоя.

  • write_query

    • Описание: Выполнение команд DDL (CREATE, ALTER, DROP), DML (INSERT, UPDATE, DELETE) или других команд StarRocks, которые не возвращают ResultSet.
    • Входные данные: 
      {
  "query": "SQL command string",
  "db": "database name (optional, uses default database if not specified)"
}
    • Выходные данные: Текстовое содержимое, подтверждающее успех (например, "Query OK, X rows affected") или сообщающее об ошибке. Изменения автоматически фиксируются при успехе.

  • analyze_query

    • Описание: Анализ запроса и получение результата анализа с использованием профиля запроса или explain analyze.
    • Входные данные: 
      {
  "uuid": "Query ID, a string composed of 32 hexadecimal digits formatted as 8-4-4-4-12",
  "sql": "Query SQL to analyze",
  "db": "database name (optional, uses default database if not specified)"
}
    • Выходные данные: Текстовое содержимое с результатами анализа запроса. Использует ANALYZE PROFILE FROM, если указан uuid, в противном случае использует EXPLAIN ANALYZE, если указан sql.

  • query_and_plotly_chart

    • Описание: Выполняет SQL-запрос, загружает результаты в Pandas DataFrame и генерирует график Plotly, используя предоставленное выражение Python. Предназначен для визуализации в поддерживающих пользовательских интерфейсах.
    • Входные данные: 
      {
  "query": "SQL query to fetch data",
  "plotly_expr": "Python expression string using 'px' (Plotly Express) and 'df' (DataFrame). Example: 'px.scatter(df, x=\"col1\", y=\"col2\")'",
  "db": "database name (optional, uses default database if not specified)"
}
    • Выходные данные: Список, содержащий:
      1. TextContent: Текстовое представление DataFrame и примечание о том, что график предназначен для отображения в пользовательском интерфейсе.
      2. ImageContent: Сгенерированный график Plotly, закодированный как изображение PNG в формате base64 (image/png). Возвращает текстовое сообщение об ошибке в случае сбоя или если запрос не вернул данных.

  • table_overview

    • Описание: Получение обзора конкретной таблицы: столбцы (из DESCRIBE), общее количество строк и образцы строк (LIMIT 3). Использует кэш в памяти, если только refresh не равно true.
    • Входные данные: 
      {
  "table": "Table name, optionally prefixed with database name (e.g., 'db_name.table_name' or 'table_name'). If database is omitted, uses STARROCKS_DB environment variable if set.",
  "refresh": false // Optional, boolean. Set to true to bypass the cache. Defaults to false.
}
    • Выходные данные: Текстовое содержимое, содержащее форматированный обзор (столбцы, количество строк, образцы данных) или сообщение об ошибке. Кэшированные результаты включают предыдущие ошибки, если применимо.

  • db_overview

    • Описание: Получение обзора (столбцы, количество строк, образцы строк) для всех таблиц в указанной базе данных. Использует кэш уровня таблицы для каждой таблицы, если только refresh не равно true.
    • Входные данные: 
      {
  "db": "database_name", // Optional if default database is set.
  "refresh": false // Optional, boolean. Set to true to bypass the cache for all tables in the DB. Defaults to false.
}
    • Выходные данные: Текстовое содержимое, содержащее объединенные обзоры для всех таблиц, найденных в базе данных, разделенные заголовками. Возвращает сообщение об ошибке, если к базе данных невозможно получить доступ или она не содержит таблиц.

Ресурсы

Прямые ресурсы

  • starrocks:///databases
    • Описание: Выводит список всех баз данных, доступных настроенному пользователю.
    • Эквивалентный запрос: SHOW DATABASES
    • MIME-тип: text/plain

Шаблоны ресурсов

  • starrocks:///{db}/{table}/schema

    • Описание: Получает определение схемы конкретной таблицы.
    • Эквивалентный запрос: SHOW CREATE TABLE {db}.{table}
    • MIME-тип: text/plain

  • starrocks:///{db}/tables

    • Описание: Выводит список всех таблиц в конкретной базе данных.
    • Эквивалентный запрос: SHOW TABLES FROM {db}
    • MIME-тип: text/plain

  • proc:///{+path}

    • Описание: Предоставляет доступ к внутренней системной информации StarRocks, аналогично команде Linux /proc. Параметр path задаёт нужный информационный узел.
    • Эквивалентный запрос: SHOW PROC '/{path}'
    • MIME-тип: text/plain
    • Типичные пути:
      • /frontends — информация об узлах FE.
      • /backends — информация об узлах BE (для развёртываний, не являющихся облачно-нативными).
      • /compute_nodes — информация об узлах CN (для облачно-нативных развёртываний).
      • /dbs — информация о базах данных.
      • /dbs/<DB_ID> — информация о конкретной базе данных по ID.
      • /dbs/<DB_ID>/<TABLE_ID> — информация о конкретной таблице по ID.
      • /dbs/<DB_ID>/<TABLE_ID>/partitions — информация о партициях таблицы.
      • /transactions — информация о транзакциях, сгруппированная по базам данных.
      • /transactions/<DB_ID> — информация о транзакциях для конкретного ID базы данных.
      • /transactions/<DB_ID>/running — выполняющиеся транзакции для ID базы данных.
      • /transactions/<DB_ID>/finished — завершённые транзакции для ID базы данных.
      • /jobs — информация об асинхронных заданиях (изменение схемы, Rollup и т. д.).
      • /statistic — статистика по каждой базе данных.
      • /tasks — информация о задачах агента.
      • /cluster_balance — информация о состоянии балансировки нагрузки.
      • /routine_loads — информация о заданиях Routine Load.
      • /colocation_group — информация о группах Colocation Join.
      • /catalog — информация о настроенных каталогах (например, Hive, Iceberg).

Подсказки

Не определены для этого сервера.

Поведение кэширования

  • Инструменты table_overview и db_overview используют кэш в памяти для хранения сгенерированного обзорного текста.
  • Ключом кэша является кортеж из (database_name, table_name).
  • При вызове table_overview сначала проверяется кэш. Если результат существует и параметр refresh равен false (по умолчанию), закэшированный результат возвращается немедленно. В противном случае данные извлекаются из StarRocks, сохраняются в кэше, а затем возвращаются.
  • При вызове db_overview выводится список всех таблиц в базе данных, а затем предпринимается попытка получить обзор для каждой таблицы с использованием той же логики кэширования, что и для table_overview (сначала проверка кэша, извлечение при необходимости и если refresh равен false или произошёл промах кэша). Если refresh равен true для db_overview, это принудительно обновляет данные для всех таблиц в этой базе данных.
  • Переменная окружения STARROCKS_OVERVIEW_LIMIT задаёт мягкий лимит максимальной длины строки обзора, генерируемой для каждой таблицы при заполнении кэша, помогая управлять использованием памяти.
  • Закэшированные результаты, включая любые сообщения об ошибках, возникшие при первоначальном извлечении, сохраняются и возвращаются при последующих попаданиях в кэш.

Отладка

После запуска mcp-сервера для отладки можно использовать инспектор:

npx @modelcontextprotocol/inspector

Демонстрация

MCP Demo Image