💰 Personal Finance Assistant — MCP + Gemini

ИИ-помощник для управления финансами, который позволяет задавать вопросы о ваших расходах обычным языком. Он построен на Model Context Protocol (MCP), чтобы связывать Google Gemini с реальными инструментами — базой данных SQL, моделями прогнозирования и обнаружением аномалий, а не со скриптовым чат-ботом, который просто умеет разговаривать.

🔗 Живое демо: mcp-finance-assistant-z6txg3k6xparasajcsvftrr.streamlit.app

Что это умеет

Задавайте ему такие вопросы:

• «Сколько я потратил на еду в этом месяце?»

• «Сравни мои расходы в августе и июле»

• «Добавь расход 250 на Uber в аэропорт» — категорию он определяет сам

• «Сколько я потрачу на еду в следующем месяце?» — реальный ML-прогноз, а не догадка

Он также проактивно помечает необычные расходы в момент загрузки страницы, без запроса.

Related MCP server: Expense Tracker MCP Server

Почему MCP

В большинстве демо ИИ-трекеров расходов ответы чат-ботов жёстко зашиваются или LLM просто прикручивается к статическим данным. Этот проект, напротив, создаёт настоящий MCP-сервер — стандартизированный способ (представленный Anthropic) для ИИ-модели: искать и вызывать реальные инструменты. Gemini читает доступные инструменты, решает, какие из них нужны, вызывает их через протокол MCP и принимает решения на основе фактических результатов. Это тот же паттерн, который используется в продакшн-системах ИИ-агентов, а не игрушечная симуляция.

Архитектура

User question → Streamlit UI → Gemini (decides which tool to call)
                                      ↓
                          MCP Server (server.py)
                                      ↓
                          SQLite Database (real transaction data)
                                      ↓
                     Tool result → back to Gemini → plain-English answer

Для многошаговых запросов (например, когда расход добавляется без категории) Gemini выполняет цепочку нескольких вызовов инструментов: сначала запрашивает существующие категории, затем выбирает правильную категорию, и только потом добавляет расход — до 3 шагов на вопрос.

Возможности

• 7 инструментов MCP: запрос сумм, сравнение месяцев, список последних расходов, добавление расходов, получение категорий, прогнозирование расходов, обнаружение аномалий

• Настоящий ML, а не правила: forecast_next_month использует scikit-learn LinearRegression на исторических тенденциях; detect_anomaly использует модель IsolationForest (обучение без аннотатора) вместо жёстко заданного порога

• Категоризация через LLM: опишите расход обычным языком, и Gemini сам подберёт нужную категорию, используя цепочку вызовов инструментов

• Проактивные инсайды: автоматическая проверка аномалий выполняется при загрузке страницы, без каких-либо вопросов

• Память диалога: уточняющие вопросы понимают контекст более ранних сообщений в чате

• Реальные данные: более 240 записей о тратахреальных транзакциях, включая 231 импортированную и очищенную запись из публичного датасета Kaggle по личным расходам

• Продакшн-практики: полная обработка ошибок и проверка входных данных во всех инструментах, структурированное логирование (app.log) и набор из 8 тестов pytest, проверяющий расчёты по известным данным

Технологии

Python · MCP SDK · Google Gemini (google-genai) · SQLite · scikit-learn · Streamlit · pytest

Локальный запуск

git clone https://github.com/srushtikochare/mcp-finance-assistant
cd mcp-finance-assistant
pip install -r requirements.txt

Создайте файл .env:

GOOGLE_API_KEY=your_api_key_here

Затем выполните:

streamlit run app.py

Запуск тестов

pytest test_server.py -v

8 тестов покрывают правильность сумм, обработку ошибок и поведение ML-инструментов — все проходят.

Реальная трудность, с которой я столкнулся

Структура MCP Python SDK изменилась с момента написания большей части доступной документации: класса, который я ожидал (FastMCP), не оказалось в установленной версии. Вместе с тем, я не руководился догадками, а изучил реально установленный пакет (dir(mcp.server)) и обнаружил правильный текущий класс (MCPServer) и поверхность API. Отладка в условиях эволюционирующей библиотеки с неполной документацией, а не стабильной и удобной для туториалов, стала самой полезной частью при создании этого проекта.

Возможные следующие шаги

• Поддержка нескольких пользователей с индивидуальными входами

• OCR-распознание чеков и выписок для автоматического занесения расходов

• Ретрай-логика с backoff для устойчивости при работе с внешними API

Автор

Srushti Kochare — B.Tech Artificial Intelligence & Data Science, YCCE Nagpur