rosstat-mcp: доступ ИИ-агентов к российской макростатистике¶
rosstat-mcp — плагин для Claude Code, Codex, Cursor, Kimi Code и Qwen Code, который подключает ИИ-агента к данным проекта clickhouse-import-rosstat через Model Context Protocol (MCP). Агент получает доступ к каталогу показателей и read-only витринам staging-ClickHouse: макро- и финансовым рядам Росстата, Банка России, Минфина и MOEX.
Плагин решает две задачи. MCP-сервер rosstat-staging передаёт агенту результаты запросов к данным, а скил rosstat-sql объясняет, как выбрать правильный ряд и написать корректный запрос. В составе нет агентов, команд и хуков.
Как устроен плагин¶
Взаимодействие выглядит так:
Клиент с ИИ-агентом
→ манифест rosstat-mcp
→ HTTPS MCP rosstat-staging
→ read-only витрины v_* в staging-ClickHouse
В манифестах указан удалённый HTTP endpoint https://mcp.selfinvesting.ru:8443/mcp, а не команда запуска локального сервера. Агент не подключается к ClickHouse напрямую: запросы проходят через MCP, где действует ограничение на чтение.
Плагин содержит два компонента:
| Компонент | Назначение |
|---|---|
MCP rosstat-staging |
Доступ к витринам v_*, каталогу v_series_catalog и служебным представлениям system.tables / system.columns |
Скил rosstat-sql |
Поиск рядов, проверка их смысла и единиц, выбор витрины, шаблоны SQL и правила работы с винтажами |
Скил написан на английском языке, но предписывает агенту отвечать пользователю по-русски. Официальные названия показателей, значения title и description нужно сохранять без перефразировки: по ним пользователь может проверить, какой именно ряд использован.
Установка и настройка¶
Получение токена¶
Токен выдаёт владелец репозитория. До запуска клиента его нужно поместить в переменную окружения ROSSTAT_MCP_TOKEN:
export ROSSTAT_MCP_TOKEN=<токен>
В Cursor токен задаётся в настройках плагина: Plugins → Configure → ROSSTAT_MCP_TOKEN. В манифестах хранится только ссылка на переменную, а не её значение. Токен нельзя добавлять в Markdown, JSON-манифесты, SQL или примеры для других пользователей.
Команды установки¶
| Клиент | Установка |
|---|---|
| Claude Code | claude plugin marketplace add kmlebedev/rosstat-mcpclaude plugin install rosstat-mcp@rosstat-mcp |
| Codex | codex plugin marketplace add kmlebedev/rosstat-mcpcodex plugin add rosstat-mcp@rosstat-mcp |
| Kimi Code | /plugins install https://github.com/kmlebedev/rosstat-mcp |
| Qwen Code | qwen extensions install kmlebedev/rosstat-mcp |
| Cursor | /add-plugin https://github.com/kmlebedev/rosstat-mcp |
После установки начните новую сессию или выполните /reload. Для Claude Code подключение проверяется командой:
claude mcp list
В списке должна быть запись plugin:rosstat-mcp:rosstat-staging с HTTP-адресом сервера и статусом Connected. Отсутствие токена или неверный токен приводит к ответу 401.
Как обратиться к скилу¶
При работе с rosstat-staging агент подхватывает rosstat-sql автоматически. Явный вызов:
- Claude Code и Qwen Code:
/rosstat-mcp:rosstat-sql; - Codex, Cursor и Kimi Code: по имени
rosstat-sql.
Доступные данные и границы доступа¶
Центральная точка поиска — v_series_catalog. В каталоге указаны источник, код ряда, официальное название, единица измерения, частота и описание. По совпадающим названиям нельзя судить о содержимом: соседние ряды могут различаться охватом, периодом и масштабом значений.
Доступ устроен следующим образом:
| Объект или операция | Доступ |
|---|---|
Витрины v_* в базе default |
Чтение разрешено |
system.tables, system.columns |
Чтение разрешено для поиска витрин и их схем |
| Сырые таблицы | Сервер возвращает ACCESS_DENIED с кодом 497 |
| DDL и запись | Запрещены; пользователь MCP работает с readonly = 2 |
| Настройки текущей сессии | Разрешены |
Доступны не только текущие значения. Параметризованное представление v_point_in_time_asof позволяет восстановить, какие версии показателей были известны до выбранной даты. Его покрытие нужно проверять отдельно: это не универсальная история всех витрин.
Первый запрос к данным¶
После установки можно дать агенту такой запрос:
Через
rosstat-stagingнайди ряд ключевой ставки Банка России вv_series_catalog. Покажи последнее значение, дату периода, единицу измерения иmax(date). Назови использованную витрину и приведи SQL.
Ответ должен содержать не только число, но и:
- точное название и код ряда;
- дату периода, к которому относится значение;
- единицу измерения и частоту;
- дату последнего наблюдения
max(date); - SQL, которым получен результат.
Если агент нашёл похожие ряды, он должен объяснить выбор по description, unit и origin, а не по созвучию кода.
Как rosstat-sql выбирает ряд и витрину¶
Рабочий процесс состоит из пяти шагов.
- Найти ряд в каталоге. Один запрос должен охватывать все понятия вопроса и возвращать
unitиfrequency. Для русских названий используются основы слов, а коды рядов копируются без сокращений. - Проверить смысл. Описание и единица важнее кода. Например, ставка может храниться как доля
0.187или как процент18.76; перед сравнением такие значения нужно привести к одной единице. - Найти витрину по
source. Название источника не всегда совпадает с названием витрины. Скил предлагает искать литерал источника вcreate_table_queryчерезsystem.tables, затем читать колонки и комментарии черезsystem.columns. - Выполнить расчёт в ClickHouse. Агрегаты, соединения и производные вычисляются на сервере. В ответ запрашивается результат, а не большой массив исходных строк.
- Сформулировать ответ. Число сопровождается датой, единицей и точным рядом; пропуски, дубли и пересмотры указываются явно.
Примеры SQL¶
Примеры ниже взяты из скила и его шаблонов. Код ряда в собственном запросе нужно скопировать из v_series_catalog.
Поиск показателя¶
SELECT source, series, title, unit, frequency
FROM v_series_catalog
WHERE multiSearchAnyCaseInsensitiveUTF8(title, ['ключев', 'курс доллар'])
LIMIT 50
LIMIT здесь ограничивает только список кандидатов при исследовании каталога. Нельзя использовать его для обрезания временного ряда перед расчётом.
Последнее значение и свежесть¶
SELECT series, max(date) AS last_date, round(argMax(value, date), 2) AS last_value, count() AS points
FROM v_rosstat_macro
WHERE series = 'Индексы потребительских цен на услуги по Российской Федерации'
GROUP BY series
argMax(value, date) возвращает значение на последнюю дату, а max(date) позволяет проверить свежесть данных.
Среднее и значение на конец месяца для дневного ряда¶
SELECT series, toStartOfMonth(date) AS month,
round(avg(value), 2) AS avg_value, round(argMax(value, date), 2) AS month_end, count() AS days
FROM v_cbr_macro
WHERE series IN ('cbr_currency_usd', 'cbr_key_rate') AND date >= '2025-01-01'
GROUP BY series, month
ORDER BY series, month
Здесь среднее и последнее значение месяца отвечают на разные вопросы. Выбор между ними зависит от методики показателя, а не от желаемого результата.
Правила корректных запросов¶
Даты и периоды¶
date обозначает период наблюдения, а не дату публикации. У месячных рядов Росстата точка обычно стоит на конец месяца; у части квартальных источников квартал датируется первым числом следующего квартала. Перед названием периода нужно прочитать комментарий колонки и описание ряда.
Для календарных группировок используются toStartOfMonth, toMonday или toStartOfInterval(d, INTERVAL 1 MONTH). Начало недели через toMonday выбирается явно. Для DateTime указывается часовой пояс Europe/Moscow и в функциях, и в литералах toDateTime; сервер не находится в московском часовом поясе.
Цепные индексы¶
Месячный индекс потребительских цен показывает изменение к предыдущему месяцу. Годовое изменение вычисляется произведением двенадцати индексов:
г/г, % = (Π(value_i / 100) − 1) × 100
Складывать месячные индексы нельзя. В оконном расчёте нужно доказать, что окно содержит двенадцать последовательных месяцев: при пропуске ROWS BETWEEN 11 PRECEDING захватит более длинный календарный период. При нескольких рядах окно обязательно разделяется через PARTITION BY series.
Пропуски и дубли¶
Отсутствующая строка не равна нулю. WITH FILL допустим только там, где отсутствие действительно означает нулевое значение, с шагом, соответствующим частоте ряда.
Перед агрегированием сравниваются count() и uniqExact(<ключ>). Если они различаются, выбирается версия через argMax(value, <колонка версии>) либо сообщается о конфликте. Произвольная строка через any(value) не подходит.
Производительность и точность¶
Фильтры ставятся по исходным колонкам, например series = … и date >= …. Функция над фильтруемой колонкой может помешать использованию ключа и привести к полному сканированию.
Для тяжёлого запроса сначала выполняется EXPLAIN ESTIMATE, а ограничение SETTINGS max_execution_time = 30 защищает от долгого расчёта. Для русского текста используются substringUTF8 и lengthUTF8; байтовые функции могут разрезать символы. Значения Float32 округляются в результате.
Данные «как было известно на дату»¶
Официальная статистика пересматривается. Текущая витрина показывает последнюю версию прошлого периода, поэтому для исторического прогноза или бэктеста она может раскрыть информацию, которой на дату расчёта ещё не было.
Point-in-time слой включает:
v_point_in_time— опубликованные версии точек сperiod_date,published_at,vintageиvintage_label;v_point_in_time_asof(as_of='YYYY-MM-DD')— последнюю версию каждой точки среди опубликованных строго раньшеas_of;v_point_in_time_version— версию набора данных.
Условие отбора — published_at < as_of. Публикация в сам день as_of исключается. Поскольку v_point_in_time_asof является параметризованным представлением, DESCRIBE без аргумента завершается ошибкой.
Справка репозитория указывает документированное покрытие только для источника cbr_dip_bulletin — бюллетеня Банка России «О чём говорят тренды». Перед использованием слоя для другого показателя нужно проверить его наличие через SELECT DISTINCT source, series FROM v_point_in_time.
Диагностика¶
| Симптом | Причина и действие |
|---|---|
| Сервер отвечает 401 | Проверить, что токен получен, помещён в ROSSTAT_MCP_TOKEN и переменная была установлена до запуска клиента |
| MCP или скил не появился после установки | Начать новую сессию или выполнить /reload; для Claude Code проверить claude mcp list |
ACCESS_DENIED с кодом 497 |
Запрос обратился к сырой таблице; найти соответствующую витрину v_*, а не повторять тот же запрос |
DESCRIBE v_point_in_time_asof не выполняется |
Передать параметр as_of='YYYY-MM-DD': это параметризованное представление |
| Значение за прошлый период изменилось | Проверить пересмотр в v_point_in_time; для даты прошлого расчёта использовать v_point_in_time_asof |
| Агрегат не совпадает с ожиданием | Проверить дубли, пропущенные месяцы, единицы и охват ряда по каталогу; не заменять пропуски нулями |
| Ответ устарел | Повторить max(date) и argMax(value, date); не использовать число из предыдущего ответа без проверки |
Разработка репозитория¶
Для каждого клиента в репозитории хранится собственный манифест, а общие правила SQL — в skills/rosstat-sql/. Тесты проверяют:
- имена, версии и описания плагина;
- единственный MCP-сервер
rosstat-stagingи его HTTP-адрес; - отсутствие агентов, команд и хуков;
- передачу токена только через
ROSSTAT_MCP_TOKEN; - отсутствие секретов и токенов в URL;
- наличие только одного скила
rosstat-sql; - ссылки скилов на обе справки и использование в SQL только
v_*иsystem.*; - состав отслеживаемых файлов и их общий размер.
Запуск локальной проверки:
python3 -m unittest discover -s tests -v
Тот же набор выполняется в CI для каждого push и pull request. Сеть для тестов не нужна, используется только стандартная библиотека Python.
Для скила действуют ограничения: description не длиннее 300 символов, SKILL.md не больше 6144 байт, весь скил вместе с references/ не больше 10240 байт. SQL-примеры перед слиянием прогоняются на staging через MCP. Новый файл основного репозитория добавляется в TRACKED_FILES в tests/test_manifests.py, поскольку при установке содержимое репозитория передаётся пользователю.
Лицензия¶
Репозиторий распространяется по лицензии MIT. Полный текст приведён в LICENSE.
Источники¶
- README rosstat-mcp — назначение, установка и разработка.
- Манифесты клиентов: Claude Code, Codex, Cursor, Kimi Code, Qwen Code.
- Скил rosstat-sql — рабочий процесс, доступ и правила запросов.
- SQL-шаблоны — поиск витрин, последние значения, годовые и месячные расчёты.
- Point-in-time справка — винтажи, строгое условие
as_ofи покрытие. - Контрактные тесты и CI workflow.
- LICENSE — лицензия MIT.