Zen Money MCP
# 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`; другим платформам потребуется совместимая версия.
## Где получить токен Дзен-мани
Серверу нужен готовый **access token** Дзен-мани. В [документации API ZenMoney](https://github.com/zenmoney/ZenPlugins/wiki/ZenMoney-API#авторизация) описан OAuth 2.0: для собственного приложения нужно подать заявку на регистрацию OAuth-клиента. Там же в качестве способа получить токен для личного использования упомянуты уже зарегистрированные сервисы; приведённый в документации пример — [Zerro.app](https://zerro.app). Это сторонний сервис: прежде чем выдавать ему доступ, самостоятельно оцени его и запрашиваемые права.
`./bin/set-token.sh` не получает токен из аккаунта, а только скрыто принимает уже выданный access token и сохраняет его. Сервер сейчас не обновляет токены через `refresh_token`; если выданный access token истечёт и API начнёт возвращать 401, получи новый токен и повтори настройку.
## Установка и запуск
```sh
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, укажи команду и абсолютный путь к проекту. Например:
```json
{
"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 отдельно от токена Дзен-мани:
```sh
./bin/set-openai-key.sh
```
По умолчанию он записывается в `${HOME}/.config/zen_money_mcp/openai-runtime-key` с правами `600`.
3. Скопируй профиль и замени `REPLACE_WITH_NEW_TUNNEL_ID` на свой Tunnel ID:
```sh
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/...`. Затем установи его и запусти службу:
```sh
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`](LICENSE). Бинарный `bin/tunnel-client` является отдельным компонентом и не получает лицензию MIT автоматически; проверь условия его правообладателя перед распространением.
TDQS
Scored across 33 tools
Most entity-specific tools have clear boundaries, but apply_zenmoney_diff and get_zenmoney_entities overlap with nearly every create/update/list tool by offering raw access to all entities. The descriptions do explain when to use the low-level tools, which mitigates but does not eliminate the risk of misselection.
Tool names consistently use snake_case with a verb-first pattern (list_, get_, create_, update_, delete_, set_, suggest_, etc.). Domain-specific verbs like sync, apply, hide, and archive are still predictable and distinguishable.
With 33 tools, the surface is quite heavy even for a comprehensive personal finance API. Many CRUD operations could be consolidated or handled through the existing generic diff/entity tools, making the set feel bloated.
The server covers the main lifecycle for transactions, categories, accounts, budgets, and reminders, plus raw access for advanced cases. Minor gaps exist in the high-level surface, such as no dedicated merchant deletion or account deletion, but these are workable through archive or apply_zenmoney_diff.