# finpilot

Локальная аналитика банковской выписки: куда ушли деньги, какие подписки списываются, нет ли странных операций и сколько уйдёт до конца месяца.

Работает двумя способами:

- **в терминале**: `finpilot report выписка.csv`;
- **как MCP-сервер** для Claude Desktop, Claude Code, Cursor и других AI-ассистентов. Подключаете один раз и спрашиваете обычным текстом: «почему в августе я потратил вдвое больше?».

Выписка не уходит в облако. Файл читается на вашем компьютере, а ассистент получает только агрегаты и найденные операции.

## Зачем

Банковские приложения показывают траты по категориям, но не отвечают на вопросы. «Сколько я трачу на подписки в год?», «что изменилось по сравнению с прошлым месяцем?», «это двойное списание или я правда дважды ел в Теремке?» — на такие вопросы обычно приходится листать выписку руками.

[MCP (Model Context Protocol)](https://modelcontextprotocol.io) — открытый протокол, через который AI-ассистенты подключают внешние инструменты. finpilot даёт ассистенту 7 инструментов поверх вашей выписки, и модель сама решает, какие вызвать.

## Что умеет

| Инструмент MCP | Что делает |
|---|---|
| `load_statement` | загружает выписку, возвращает период и итоги |
| `spending_by_category` | расходы по категориям за месяц и изменение к прошлому |
| `top_merchants` | на какие магазины и сервисы ушло больше всего |
| `find_subscriptions` | регулярные списания: сумма, периодичность, следующая дата, стоимость в год |
| `find_unusual_transactions` | траты крупнее обычного для категории и двойные списания |
| `forecast_month` | прогноз расходов до конца месяца при текущем темпе |
| `search_transactions` | поиск операций по тексту или категории |

Плюс шаблон запроса `monthly_review`: разбор месяца с тремя конкретными советами.

Категория операции определяется так: категория банка, если она есть в выгрузке → MCC-код → ключевые слова в описании. Переводы, пополнения и снятие наличных в расходы не входят.

## Пример

На тестовой выписке из `examples/`:

```
$ finpilot report examples/sample_statement.csv

Выписка: 392 операции, 01.04.2026 — 20.09.2026

Расходы за 2026-09 (по 20.09.2026): 25 937 ₽  (в 2026-08 к тому же числу: 46 934 ₽)

  Продукты                      12 304 ₽    47%    +28%
  Кафе и рестораны               6 330 ₽    24%   +197%
  Маркетплейсы и магазины        3 094 ₽    12%    -89%
  ...

Подписки: 4, в год 21 564 ₽
  МТС                                    650 ₽  ежемесячно, следующее 12.10.2026
  Okko                                   449 ₽  ежемесячно, следующее 21.09.2026
  Яндекс Плюс                            399 ₽  ежемесячно, следующее 05.10.2026
  Telegram Premium                       299 ₽  ежемесячно, следующее 18.10.2026

Необычные операции:
  03.09.2026 13:40  Теремок                1 890 ₽  обычно в категории ~310 ₽
  03.09.2026 13:42  Теремок                1 890 ₽  обычно в категории ~310 ₽; повторное списание той же суммы в течение 10 минут

Прогноз на 2026-09: 42 766 ₽ (потрачено 25 937 ₽, осталось дней: 10)
```

## Установка

Нужен Python 3.10+.

**macOS / Linux**
```bash
git clone https://github.com/antonshkelll/finpilot-mcp.git
cd finpilot-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
finpilot report examples/sample_statement.csv
```

**Windows (PowerShell)**
```powershell
git clone https://github.com/antonshkelll/finpilot-mcp.git
cd finpilot-mcp
py -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e .
finpilot report examples\sample_statement.csv
```

## Подключение к AI-ассистенту

Понадобится полный путь к `finpilot-mcp` внутри виртуального окружения. Узнать его:

- macOS / Linux: `which finpilot-mcp` (при активированном `.venv`);
- Windows: `where finpilot-mcp`.

### Claude Desktop

Откройте Settings → Developer → Edit Config. Файл лежит в `~/Library/Application Support/Claude/claude_desktop_config.json` на macOS и в `%APPDATA%\Claude\claude_desktop_config.json` на Windows. Добавьте:

```json
{
  "mcpServers": {
    "finpilot": {
      "command": "/Users/you/finpilot-mcp/.venv/bin/finpilot-mcp",
      "env": { "FINPILOT_STATEMENT": "/Users/you/Downloads/statement.csv" }
    }
  }
}
```

На Windows путь будет вида `C:\\Users\\you\\finpilot-mcp\\.venv\\Scripts\\finpilot-mcp.exe` (обратные слэши удваиваются). Перезапустите Claude Desktop, и в списке инструментов появится finpilot.

### Claude Code

```bash
claude mcp add finpilot --env FINPILOT_STATEMENT=/path/to/statement.csv -- /path/to/.venv/bin/finpilot-mcp
```

### Cursor

Файл `~/.cursor/mcp.json`, формат тот же, что у Claude Desktop.

`FINPILOT_STATEMENT` можно не задавать. Тогда достаточно сказать ассистенту «загрузи выписку /путь/к/файлу.csv», и он вызовет `load_statement`.

## Какие выписки подходят

- **Т-Банк:** выгрузка операций в CSV из веб-версии. Колонки «Дата операции», «Сумма операции», «Категория», «MCC», «Описание» подхватываются автоматически, кодировка UTF-8 или Windows-1251.
- **Любой другой банк:** сохраните таблицу как CSV с колонками `date`, `amount`, `description` (расходы со знаком минус). Даты можно писать как `2026-09-12` или `12.09.2026`. Колонки `mcc` и `category` необязательны.

Покупки в валюте считаются по сумме в рублях (колонка «Сумма платежа» у Т-Банка). Если месяц ещё не закончился, сравнение с прошлым идёт «к тому же числу». Подписка, по которой списания прекратились, в отчёт не попадает.

Если формат не распознался, finpilot напишет, каких колонок не хватает и какие нашёл.

## Для разработчиков

```bash
pip install -e ".[dev]"
pytest -q                          # 19 тестов: реальные форматы выписок и сквозной тест MCP-сервера
python examples/make_sample.py     # пересоздать тестовую выписку
```

```
finpilot/
  statement.py    чтение CSV в единый формат
  categories.py   категории: банк → MCC → ключевые слова
  analytics.py    сводки, подписки, аномалии, прогноз
  server.py       MCP-сервер (официальный Python SDK, MCPServer)
  cli.py          текстовый отчёт
```

## Ограничения

- PDF-выписки (например, у Сбера) пока не читаются: сначала их нужно перевести в CSV.
- Категории по ключевым словам настроены под российские сервисы, а редкие мерчанты попадут в «Прочее».
- Подписка определяется по трём и более похожим списаниям с регулярным интервалом, поэтому новая подписка появится в отчёте только через три месяца.