💰 Personal Finance Assistant — MCP + Gemini

An AI-powered personal finance assistant that allows users to analyze and manage expenses using natural language. The system combines Google Gemini, Model Context Protocol (MCP), SQL data, and machine learning tools to transform a conversational request into real database queries, predictions, and anomaly detection.

🔗 Live Demo: https://mcp-finance-assistant-z6txg3k6xparsajcsvftrr.streamlit.app/

🚀 Overview

Traditional expense trackers require users to navigate filters, categories, and dashboards manually.

This project provides a conversational interface where users can simply ask:

• "How much did I spend on food this month?"

• "Compare my spending in August and July."

• "Show me my recent expenses."

• "Add an expense of ₹250 for Uber to the airport."

• "What will I spend on food next month?"

Instead of generating answers from predefined responses, Gemini determines which application tool is required, invokes it through MCP, receives the actual result, and generates a natural-language response.

The system also performs automatic anomaly detection to identify unusual spending patterns.

Related MCP server: Expense Tracker MCP Server

🎯 Key Objectives

• Enable natural-language interaction with structured financial data.

• Integrate an LLM with real application tools using Model Context Protocol (MCP).

• Provide expense analysis using a SQL database.

• Apply machine learning for spending forecasting and anomaly detection.

• Support multi-step tool execution for requests requiring multiple operations.

• Validate inputs and handle tool-level errors reliably.

• Provide automated tests for core financial calculations and tool behavior.

🏗️ System Architecture

                         ┌──────────────┐
                         │     User     │
                         └──────┬───────┘
                                │
                                ▼
                     ┌────────────────────┐
                     │   Streamlit UI     │
                     └─────────┬──────────┘
                               │
                               ▼
                     ┌────────────────────┐
                     │   Google Gemini   │
                     │  Tool Selection   │
                     └─────────┬──────────┘
                               │
                         MCP Protocol
                               │
                               ▼
                     ┌────────────────────┐
                     │    MCP Server      │
                     │     server.py      │
                     └─────────┬──────────┘
                               │
              ┌────────────────┼────────────────┐
              │                │                │
              ▼                ▼                ▼
       ┌────────────┐   ┌─────────────┐  ┌──────────────┐
       │   SQLite   │   │ Forecasting │  │   Anomaly    │
       │  Database  │   │     ML      │  │  Detection   │
       └────────────┘   └─────────────┘  └──────────────┘
              │                │                │
              └────────────────┼────────────────┘
                               ▼
                         Tool Results
                               │
                               ▼
                     ┌────────────────────┐
                     │   Google Gemini    │
                     │ Response Generation│
                     └─────────┬──────────┘
                               │
                               ▼
                         Natural Language
                            Response

Multi-step Tool Calling

Some requests require more than one operation.

For example:

"Add ₹250 for Uber to the airport."

The system can perform a sequence such as:

User Request
     ↓
Identify missing category
     ↓
Retrieve available categories
     ↓
Gemini determines appropriate category
     ↓
Add expense to database
     ↓
Return confirmation

This demonstrates how an LLM can interact with application capabilities rather than simply generating text.

✨ Features

1. Natural-Language Expense Analysis

Users can ask questions about their expenses without manually writing SQL queries or navigating filters.

Example:

"How much did I spend on food this month?"

The system retrieves the relevant financial data and returns the result in natural language.

2. MCP-Based Tool Integration

The application exposes financial operations as MCP tools that Gemini can discover and invoke.

The project currently provides 7 tools for:

• Expense totals

• Monthly comparisons

• Recent expense retrieval

• Adding expenses

• Category retrieval

• Spending forecasts

• Anomaly detection

3. Machine Learning Forecasting

The forecast_next_month tool uses scikit-learn Linear Regression to estimate future spending based on historical spending trends.

This allows the assistant to answer questions such as:

"What will I spend on food next month?"

4. Anomaly Detection

The system uses Isolation Forest, an unsupervised machine-learning algorithm, to identify potentially unusual spending patterns.

Instead of relying only on a manually defined spending threshold, the model identifies observations that differ from the learned pattern.

5. LLM-Based Categorization

When an expense is entered without an explicit category, Gemini can infer the appropriate category using available category information.

Example:

"Add ₹250 for Uber to the airport."

The system can identify the relevant category before storing the transaction.

6. Proactive Insights

The application performs an automatic anomaly check when the interface loads, allowing unusual transactions to be highlighted without requiring the user to explicitly ask.

7. Conversational Context

Follow-up questions can use information from the ongoing conversation.

Example:

User: How much did I spend on food in August?

Assistant: ₹4,850.

User: What about July?

Assistant: ₹4,120.

8. Input Validation and Error Handling

Tools validate inputs and handle invalid requests before performing database or model operations.

9. Automated Testing

The project includes a pytest test suite covering:

• Financial calculations

• Error handling

• Tool behavior

• Machine-learning tool execution

📊 Dataset

The application uses 240+ transaction records, including 231 records imported and cleaned from a public Kaggle personal-expense dataset.

The dataset is stored and queried through SQLite for application-level financial analysis.

🛠️ Tech Stack

🧪 Testing

Run the test suite using:

pytest test_server.py -v

The tests verify core calculations, error handling, and ML-related tool behavior against known data.

▶️ Running Locally

1. Clone the repository

git clone https://github.com/srushtikochare/mcp-finance-assistant
cd mcp-finance-assistant

2. Install dependencies

pip install -r requirements.txt

3. Configure the Gemini API key

Create a .env file:

GOOGLE_API_KEY=your_api_key_here

4. Run the application

streamlit run app.py

🧠 Technical Challenge

During development, the MCP Python SDK had changed from the API structure described in several available examples.

Instead of relying on outdated documentation, I inspected the installed package and its available API surface to determine the appropriate server implementation.

This required adapting the implementation to the actual installed SDK version and testing the integration against the current API.

This experience highlighted an important practical aspect of AI application development: LLM and AI infrastructure libraries evolve rapidly, so applications need to be developed against the actual SDK/API behavior rather than relying solely on older tutorials.

🔐 Current Limitations

This is currently designed as a single-user personal finance application.

It does not yet include:

• User authentication

• Separate financial profiles

• Receipt/statement OCR

• Advanced forecasting models for strong seasonal patterns

• Distributed deployment

• Advanced API rate limiting

These are potential directions for future development.

🔮 Future Improvements

• Multi-user authentication and isolated financial profiles

• Receipt and bank-statement OCR

• More advanced forecasting models

• Automatic recurring-expense detection

• Interactive spending dashboards

• Retry mechanisms with exponential backoff

• More extensive evaluation datasets

• Containerized deployment

💡 What This Project Demonstrates

This project demonstrates practical experience with:

• LLM tool calling

• Model Context Protocol (MCP)

• Agent-style application workflows

• SQL database integration

• Machine-learning integration

• Natural-language interfaces

• Anomaly detection

• Time-series-style spending forecasting

• API integration

• Input validation and error handling

• Automated testing

• Application logging

• Debugging evolving AI SDKs

👩‍💻 Author

Srushti Kochare B.Tech — Artificial Intelligence & Data Science Yeshwantrao Chavan College of Engineering (YCCE), Nagpur

GitHub: https://github.com/srushtikochare