Finance Manager MCP

Персональные финансы с самостоятельным хостингом для MCP-клиентов. Ваши банки остаются доступными только для чтения (SimpleFIN), данные живут в локальном файле SQLite, который принадлежит вам, а LLM может запрашивать лишь детерминированные итоги — он никогда не делает записей в бухгалтерскую книгу.

SimpleFIN (read-only)
    → raw_syncs (append-only JSON)
    → truth tables (accounts, transactions, rules, budgets)
    → warm-cache aggregates
    → atomic functions / MCP tools (stdio + gRPC)

Почему такая архитектура

• Идемпотентная загрузка — транзакции привязаны к идентификатору SimpleFIN, назначенному банком. Повторная синхронизация того же дампа не даёт ни одной новой строки; внешне одинаковые новые проводки никогда не схлопываются в одну.

• Детерминированная категоризация — правила регулярных выражений с подходом «первое совпадение побеждает». В цепочке записи нет ни одной модели.

• Тёплый кэш — помесячные расходы, денежные потоки, снимки чистой стоимости и повторяющиеся потоки платежей хранятся в SQLite, поэтому после перезапуска всё мгновенно доступно. Кэш — производная величина; rebuild-cache пересобирает его из таблиц-первоисточников.

• Пространства имён по UUID профиля — каждый инструмент записи требует profile_id. Разные профили никогда не пересекаются между собой.

• Двойной транспорт — stdio для Claude Desktop / Cursor, gRPC через соседний пакет GRPC-MCP.

Related MCP server: personal-finance-mcp

Установка

Python 3.11+.

python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix:    source .venv/bin/activate
pip install -e ".[dev]"
# optional gRPC transport (sibling ../GRPC-MCP)
pip install -e "../GRPC-MCP/python"
pip install -e ".[grpc]"

cp .env.example .env
# paste a Fernet key into FINANCE_ENCRYPTION_KEY
python -c "from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())"

finance-mcp init                          # creates data/finance.db + a default profile
finance-mcp profile list                  # copy the profile UUID

Как подключиться к SimpleFIN

В MCP-клиенте попросите подключить банк. Агент должен:

1. Вызвать begin_simplefin_connect (или использовать подсказку connect_simplefin).

2. Показать вам bridge.simplefin.org — вы входите, подключаете банки (только чтение), копируете одноразовый токен настройки.

3. Вызвать claim_connection с этим токеном. URL доступа хранится в зашифрованном виде.

4. По желанию — вызвать sync_now для того же profile_id.

CLI по-прежнему работает, если удобнее терминал:

finance-mcp claim-token --token "<setup-token>" --name "My Banks" --profile <PROFILE_UUID>
finance-mcp sync --profile <PROFILE_UUID>

sync безопасно запускать из Task Scheduler или cron. Перекрывающиеся временные окна не приводят к двойному пересчёту.

Запуск сервера

finance-mcp serve-stdio                   # Claude Desktop / Cursor
finance-mcp serve-grpc --auth bearer      # sibling GRPC-MCP transport
finance-mcp token new --name cursor --profile <PROFILE_UUID>

Bearer-токен печатается всего один раз. gRPC хранит только SHA-256 хэш.

Атомарные функции

Всё в finance_mcp.api — обычные функции. MCP-инструменты — это тонкие обёртки. Импортируйте библиотеку без запуска сервера:

from finance_mcp.config import Settings
from finance_mcp.core.db import Database
from finance_mcp import api

db = Database.from_settings(Settings.from_env())
print(api.net_worth(db, profile_id))

Чтение

list_accounts, get_balances, net_worth, net_worth_history, search_transactions, recent_transactions, spending_by_category, cash_flow, recurring_streams, upcoming_payments, budget_status, list_rules, sync_status, profile_info, list_profiles, begin_simplefin_connect

Запись (всегда требует profile_id)

claim_connection, create_rule, update_rule, delete_rule, apply_rules, create_budget, update_budget, delete_budget, sync_now

Тесты

Набор тестов герметичен — только синтетические фикстуры, никаких учётных данных.

pytest -q

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

• URL доступа SimpleFIN шифруются ключом FINANCE_ENCRYPTION_KEY (Fernet). Обязательно сделайте резервную копию ключа.

• Bearer-токены gRPC хранятся в виде хэшей.

• Инструменты чтения открывают SQLite с mode=ro. Инструменты записи — единственный путь изменения данных, и они ограничены рамками профиля.

• data/ и .env игнорируются git.

Лицензия

Используйте как удобно, для личных личного хостинга финансов.