zenmoney-mcp

MCP-сервер для ZenMoney — сервиса учёта личных финансов. Позволяет ИИ-ассистенту (Claude Desktop, Claude Code, Kimi Code и др.) вносить транзакции, смотреть счета, категории и бюджеты, а также строить аналитику по расходам и доходам.

Кратко о возможностях: транзакции (просмотр, добавление, редактирование, удаление, переводы), автокатегоризация (свои локальные правила + suggest ZenMoney), справочники, бюджеты с фактом исполнения, аналитика в валюте пользователя, локальный кэш с инкрементальной синхронизацией.

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

• docs/tools.md — все инструменты MCP: параметры, форматы, примеры;
• docs/cli.md — CLI-команды, переменные окружения, файлы данных;
• docs/rules.md — правила категоризации;
• docs/scenarios.md — сценарии использования с ассистентом.

Быстрый старт

Понадобится установленный uv (Python ставить не нужно — uv скачает его сам). Дальше два шага:

1. Получите токен на zerro.app/token — авторизуйтесь через ZenMoney и скопируйте токен (способ из официальной wiki ZenMoney API).
2. Добавьте блок в конфиг своего MCP-клиента:

{
  "mcpServers": {
    "zenmoney": {
      "command": "uvx",
      "args": ["zenmoney-mcp"],
      "env": { "ZENMONEY_TOKEN": "<токен>" }
    }
  }
}

Куда вставлять (JSON-блок везде одинаковый):

• Claude Desktop — claude_desktop_config.json (Settings → Developer → Edit Config);
• Claude Code — .mcp.json в корне проекта или claude mcp add zenmoney -e ZENMONEY_TOKEN=<токен> -- uvx zenmoney-mcp;
• Kimi Code — mcp.json.

После перезапуска клиента у ассистента появится 21 инструмент zenmoney. uvx сам скачает пакет с PyPI при первом запуске.

Безопасность

• Токен в конфиге MCP-клиента хранится открытым текстом. Не коммитьте проектный .mcp.json с токеном в git — добавьте его в .gitignore или держите токен только в пользовательском (не проектном) конфиге.
• Вставляйте токен в конфиг руками, а не через ассистента: сервер устроен так, что токен читается с диска или из окружения и не проходит через ИИ-модель — модель видит только названия инструментов и их аргументы. Не присылайте токен в переписку.
• Если не хотите держать токен в конфиге вовсе — сохраните его в файл командой set-token (см. ниже), конфиг останется чистым.

Альтернативные способы авторизации

• Токен в файле: uvx zenmoney-mcp set-token — токен запрашивается интерактивно (не попадёт в историю shell) и сохраняется в token.json; блок env из конфига тогда не нужен.
• Своё OAuth-приложение (даёт авто-refresh токена): зарегистрируйте приложение у ZenMoney и выполните uvx zenmoney-mcp auth.

Детали обеих команд, переменные окружения и расположение файлов — в docs/cli.md.

Возможности и инструменты

• Синхронизация и справочники: sync, get_accounts, get_tags, get_merchants, get_instruments.
• Транзакции: get_transactions, add_transaction, update_transaction, delete_transaction, suggest_transaction.
• Правила категоризации: add_rule, list_rules, delete_rule, test_rules, reclassify.
• Бюджеты: get_budgets, set_budget.
• Аналитика: spending_by_category, income_vs_expense, account_balances, monthly_summary.

Полный справочник с параметрами и примерами — docs/tools.md.

Разработка

git clone https://github.com/Romandredan/zenmoney-mcp
cd zenmoney-mcp
uv sync          # установить зависимости
uv run pytest -q # тесты (без сети, API замокан)

Запуск локальной версии сервера — uv run zenmoney-mcp; чтобы MCP-клиент использовал исходники вместо пакета с PyPI:

{
  "mcpServers": {
    "zenmoney": {
      "command": "uv",
      "args": ["run", "--directory", "<путь к репозиторию>", "zenmoney-mcp"],
      "env": { "ZENMONEY_TOKEN": "<токен>" }
    }
  }
}

В src/zenmoney_mcp/zenmoney/ завендорен клиент sakost/zenmoney-api (MIT, см. NOTICE.md в том же каталоге).