Zen Money MCP

MCP-сервер для личного аккаунта Дзен-мани. Он использует официальный API Дзен-мани для чтения данных, анализа расходов и выполнения финансовых операций. Сервер работает через stdio и не открывает публичный HTTP-порт.

Каждому пользователю нужна собственная установка и собственный токен Дзен-мани. Не подключай личный токен к общему серверу для других пользователей: инструменты умеют читать и менять финансовые данные аккаунта.

Требования

• Node.js 20 или новее и npm.

• MCP-клиент с поддержкой stdio-серверов.

• Доступ в интернет к api.zenmoney.ru.

• Для установки Secure MCP Tunnel на Linux x86-64 доступен бинарный bin/tunnel-client; другим платформам потребуется совместимая версия.

Related MCP server: OpenBudget MCP Server

Где получить токен Дзен-мани

Серверу нужен готовый access token Дзен-мани. В документации API ZenMoney описан OAuth 2.0: для собственного приложения нужно подать заявку на регистрацию OAuth-клиента. Там же в качестве способа получить токен для личного использования упомянуты уже зарегистрированные сервисы; приведённый в документации пример — Zerro.app. Это сторонний сервис: прежде чем выдавать ему доступ, самостоятельно оцени его и запрашиваемые права.

./bin/set-token.sh не получает токен из аккаунта, а только скрыто принимает уже выданный access token и сохраняет его. Сервер сейчас не обновляет токены через refresh_token; если выданный access token истечёт и API начнёт возвращать 401, получи новый токен и повтори настройку.

Установка и запуск

git clone https://github.com/bulava92/zen-money-mcp.git
cd zen-money-mcp
npm ci --ignore-scripts --no-audit --no-fund
./bin/set-token.sh
npm start

set-token.sh запрашивает токен скрытым вводом и хранит его вне репозитория: ${HOME}/.config/zen_money_mcp/access-token. Каталог создаётся с правами 700, файл — 600. Сервер принимает только обычный файл токена без прав на чтение или запись для группы и остальных пользователей; символическая ссылка не допускается.

Путь можно изменить через ZENMONEY_TOKEN_FILE. Если задаёшь его для службы или MCP-клиента, обеспечь права 600 и доступ тому же пользователю ОС, который запускает процесс.

Для MCP-клиента, который поддерживает stdio, укажи команду и абсолютный путь к проекту. Например:

{
  "mcpServers": {
    "zen-money": {
      "command": "node",
      "args": ["/absolute/path/to/zen-money-mcp/src/server.mjs"]
    }
  }
}

Формат файла конфигурации может различаться в зависимости от MCP-клиента.

Инструменты

Синхронизация и общие данные

• sync_zenmoney — синхронизирует выбранные сущности с API; поддерживает принудительное обновление.

• get_zenmoney_profile — ID профиля и основная валюта.

• get_zenmoney_entities — читает полные исходные записи сущностей для точного просмотра полей API.

• list_instruments, list_companies — справочники валют, банков и организаций.

Счета, категории и контрагенты

• list_accounts, create_account, update_account, archive_account.

• list_categories, create_category, update_category, hide_category, delete_category.

• list_merchants, create_merchant, update_merchant.

Архивация счёта и скрытие категории сохраняют историю. Для удаления категории инструмент требует confirm: true и проверяет, что категория не используется в активных операциях. Удаление напоминания также требует confirm: true.

Операции, бюджеты и отчёты

• list_transactions — фильтрует операции по датам, счёту и категории; выдаёт результат страницами.

• create_transaction, update_transaction, delete_transaction. Последний помечает операцию удалённой в Дзен-мани, сохраняя её запись в истории синхронизации.

• summarize_spending — сводит доходы и расходы за период по валютам и категориям. Суммы разных валют не складываются.

• list_budgets, set_budget, delete_budget.

Для удаления бюджета сервер разблокирует его и устанавливает сумму в ноль, сохраняя связанные данные. Проверяй валюту и период при анализе итогов.

Напоминания и подсказки

• list_reminders, list_reminder_markers, create_reminder, update_reminder, delete_reminder.

• suggest_transaction, suggest_transactions — запрашивают у Дзен-мани подсказки категории и контрагента для одной или нескольких операций.

Низкоуровневая работа с API

• apply_zenmoney_diff создаёт и изменяет записи пакетами для поддерживаемых сущностей, включая операции, счета, категории, контрагентов, бюджеты и напоминания.

• Частичное изменение объединяется с текущей записью. Новые записи связываются с текущим профилем.

• Для удаления через apply_zenmoney_diff нужно явно передать confirmDeletes: true. Высокоуровневые delete_category и delete_reminder требуют confirm: true. Системные сущности user, instrument и company доступны только для чтения.

Используй apply_zenmoney_diff только когда высокоуровневого инструмента недостаточно: этот инструмент позволяет менять больше полей API за один вызов.

Данные и безопасность

• Токен отправляется как Bearer только на https://api.zenmoney.ru/v8/diff/ и https://api.zenmoney.ru/v8/suggest/.

• Транзакционная история хранится в памяти процесса и не записывается сервером в локальную базу или файлы.

• stdout зарезервирован для MCP-протокола; диагностика возвращается через stderr/MCP-ответы.

• Токен даёт доступ к данным Дзен-мани в соответствии с правами аккаунта. Не передавай его в сообщения, аргументы команд, Git или логи.

• Скрипт настройки защищает обычный файл токена правами, но .gitignore не удалит секрет, если его вручную закоммитили. Перед публикацией проверь историю репозитория.

• Перед созданием, изменением или удалением финансовой записи проверь сумму, валюту, счёт и категорию.

Secure MCP Tunnel и systemd

Tunnel — необязательный способ подключить сервер через Secure MCP Tunnel. Локальный stdio-запуск не требует Tunnel ID или runtime API key.

1. Создай Secure MCP Tunnel и получи Tunnel ID и runtime API key.

2. Сохрани runtime key отдельно от токена Дзен-мани:

   ./bin/set-openai-key.sh

   По умолчанию он записывается в ${HOME}/.config/zen_money_mcp/openai-runtime-key с правами 600.

3. Скопируй профиль и замени REPLACE_WITH_NEW_TUNNEL_ID на свой Tunnel ID:

   install -d -m 700 "$HOME/.config/zen_money_mcp"
   cp deploy/tunnel-profile.yaml.example "$HOME/.config/zen_money_mcp/tunnel-profile.yaml"
   chmod 600 "$HOME/.config/zen_money_mcp/tunnel-profile.yaml"

4. В профиле проверь путь в api_key и команду node .../src/server.mjs; укажи пути и домашний каталог пользователя, который запускает службу.

5. При настройке systemd сначала отредактируй deploy/zen-money-mcp-tunnel.service.example: в шаблоне используются пользователь vscode, каталог /var/www/zen-money-mcp и профиль /home/vscode/.... Затем установи его и запусти службу:

   sudo install -o root -g root -m 0644 deploy/zen-money-mcp-tunnel.service.example /etc/systemd/system/zen-money-mcp-tunnel.service
   sudo systemctl daemon-reload
   sudo systemctl enable --now zen-money-mcp-tunnel.service

Шаблон профиля слушает health endpoint только на 127.0.0.1. Не открывай его наружу и не передавай runtime key другим людям. Бинарный bin/tunnel-client в репозитории собран для Linux x86-64; для другой ОС установи совместимую версию отдельно. Перед повторным распространением бинарного файла проверь условия его правообладателя.

Устранение неполадок

• «Токен не настроен»: выполни ./bin/set-token.sh от имени пользователя, запускающего MCP-сервер.

• 401 от API: токен отклонён; проверь его в настройках Дзен-мани и сохрани заново.

• 403 от API: у токена нет доступа; создай или обнови токен с нужными разрешениями.

• Ошибка прав на файл: установи режим 600, проверь владельца и убедись, что путь не является символической ссылкой.

• Tunnel не запускается: проверь Tunnel ID, runtime key, путь к файлу ключа, абсолютный путь проекта и systemd-журнал службы.

Лицензия

Исходный код проекта распространяется по лицензии MIT; текст находится в LICENSE. Бинарный bin/tunnel-client является отдельным компонентом и не получает лицензию MIT автоматически; проверь условия его правообладателя перед распространением.