Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@x5-mcp Синхронизируй мои покупки за август 2026"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP-сервер для Codex, который загружает историю покупок из личного кабинета X5 Club в локальную SQLite-базу, а потом позволяет спрашивать у агента про траты, чеки, товары, категории и изменение цен.
Работает локально на компьютере пользователя. Публичный сервер не нужен, ваши чеки не хранятся у автора пакета.
Node.js 24.x
Codex или другой MCP-клиент со stdio transport
Аккаунт X5 Club и cookie из браузерной сессии
Related MCP server: ExpenseTracker MCP Server
Добавьте MCP-сервер в конфиг Codex:
[mcp_servers.x5]
command = "npx"
args = ["-y", "x5-mcp"]
startup_timeout_sec = 20
tool_timeout_sec = 300
[mcp_servers.x5.env]
X5_COOKIE = "name=value; other=value"Перезапустите Codex или обновите MCP-подключения. После этого можно писать обычные запросы:
Синхронизируй мои покупки с 2026-08-01 по 2026-08-31Покажи расходы по неделям за август 2026Найди мои покупки кофе и покажи, как менялась ценаКакие товары я чаще всего покупал за последние 3 месяца?Войдите в свой аккаунт на https://x5club.ru.
Откройте историю покупок.
Откройте DevTools -> Network.
Обновите историю или загрузите следующую страницу.
Найдите запрос POST /lk/history.data.
В Request Headers скопируйте значение заголовка Cookie.
Вставьте только значение, без префикса Cookie:.
Не отправляйте cookie в чат, issue, pull request или сторонним людям. Cookie дает доступ к вашему аккаунту.
По умолчанию SQLite создается локально:
Windows: %LOCALAPPDATA%/x5-purchases-mcp/x5.sqlite
macOS/Linux: $XDG_DATA_HOME/x5-purchases-mcp/x5.sqlite или ~/.local/share/x5-purchases-mcp/x5.sqlite
Можно задать свой путь:
[mcp_servers.x5.env]
X5_COOKIE = "name=value; other=value"
X5_DB_PATH = "C:/Users/me/x5-purchases.sqlite"[mcp_servers.x5.env]
X5_COOKIE = "name=value; other=value"
X5_DB_PATH = "C:/Users/me/x5-purchases.sqlite"
X5_NETWORK_CODES = "D,S,VK,SL,VP"
X5_REQUEST_TIMEOUT_MS = "30000"
X5_PAGE_DELAY_MS = "500"
X5_MAX_PAGES_PER_MONTH = "1000"
X5_SYNC_FROM = "2026-01-01"
X5_ENABLE_SYNC_TOOL = "1"Если поставить X5_ENABLE_SYNC_TOOL = "0", агент сможет анализировать уже загруженную базу, но не будет сам ходить в X5 за новыми данными.
x5_sync_history: загрузить или обновить чеки за период
x5_get_sync_status: проверить покрытие и свежесть данных
x5_get_recent_receipts: последние чеки
x5_get_receipt: один чек с позициями
x5_get_spending: траты по дням, неделям или месяцам
x5_search_purchases: поиск покупок по названию
x5_get_product_history: история покупок и цен конкретного товара
x5_get_top_products: частые товары
x5_get_categories: исходные коды категорий
x5_get_category_spending: предварительная оценка трат по категориям
x5_get_price_changes: сравнение первой и последней известной цены
Первый импорт лучше делать за явный период: например, с 2026-08-01 по 2026-08-31.
Отсутствие чеков в базе не значит нулевые траты, пока период не был успешно синхронизирован.
Денежные поля *_minor возвращаются в копейках RUB.
Категорийные суммы являются оценкой, потому что считаются по позициям чека.
X5 может менять формат личного кабинета без предупреждения; если синхронизация сломалась, обновите пакет и cookie.
pnpm install --frozen-lockfile
pnpm build
pnpm testЛокальный запуск stdio-сервера:
pnpm startПубликация новой версии:
pnpm build
npm publish --access publicИсходные коды категорий и число позиций. Названия категорий не выдумываются.
Inputs: to (required), from (required), groupBy, network.
Предварительная ОЦЕНКА трат по категориям: pricePromo × quantity. Семантика цены не подтверждена, это не точные итоги чеков.
Inputs: to (required), from (required), limit, network, +1 more.
Сравнить первую и последнюю известную цену каждого PLU за период, раздельно по сети и единице. Акции могут объяснять разницу.
Inputs: to (required), from (required), limit, network, +1 more.
История PLU, цены и количество. PLU найдите через x5_search_purchases. Сети и единицы не смешиваются в сводке.
Inputs: pluId (required), to, from, limit, +2 more.
Один чек и до 500 его позиций; itemsCount показывает полное число позиций.
Inputs: id (required).
Последние чеки из SQLite без состава; limit/offset. Состав — x5_get_receipt.
Inputs: limit, offset.
Траты по суммам чеков, без удвоения по товарам. Период включительно, сеть по исходному коду. null — неизвестно.
Inputs: to (required), from (required), groupBy, network.
Покрытие истории, сети, свежесть и результаты последних синхронизаций. Проверять перед аналитикой.
Inputs: no named parameters.
Частые товары по числу разных чеков, с количеством и последней покупкой. Фильтры периода, сети, категории.
Inputs: to (required), from (required), limit, network, +1 more.
Локальный поиск по названию товара без учёта регистра, ё/е; фильтры дат, сети, категории; limit/offset.
Inputs: query (required), to, from, limit, +3 more.
Загрузить чеки X5 в локальную SQLite. Сетевой запрос, обновляет локальный кэш. Первый запуск требует from/to; далее перекрытие 7 дней. Большой импорт запускайте CLI.
Inputs: to, from.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 11 tools
Each tool targets a distinct function: syncing, sync status, receipt browsing/detail, spending, product search, product history, top products, categories, category spending, and price changes. The two spending-related tools are clearly separated by receipt totals versus estimated category totals.
All names follow a consistent x5_ prefix and snake_case convention, with read operations predominantly using x5_get_* plus clearly distinct action verbs like x5_sync_history and x5_search_purchases. There is no mixing of naming styles.
Eleven tools is well within the ideal range and each tool contributes a clear part of the workflow: data ingestion, status checking, receipt access, and analytics. None feel redundant or unnecessary.
The surface covers the full local receipt analytics workflow: sync, verify sync status, list/read receipts, search products, and perform spending/category/price analysis. Minor limitations such as large imports being delegated to CLI and receipts with more than 500 line items not being paginated prevent a perfect score.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Track expenses from your AI chat: log, categorize, monthly CSV reports. All data is local.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
