FinChat

FinChat is an AI-powered personal finance assistant built using the Model Context Protocol (MCP). It exposes financial management and analytics capabilities as reusable tools that can be discovered and executed by MCP-compatible AI clients.

The project demonstrates how Large Language Models (LLMs) can interact with external systems through structured tools to perform tasks such as transaction management, spending analysis, financial insights generation, and savings goal tracking.

Note: This project currently uses synthetic/dummy financial data for demonstration purposes. It does not connect to real bank accounts or personal financial information.

---

✨ Features at a Glance

• Transaction Management – Add, retrieve, and query financial transactions
• Spending Analytics – Analyze spending by category and generate financial insights
• Goal Tracking – Set, update, and monitor progress toward savings goals
• MCP Integration – Discover and execute tools through standardized protocol
• AI-Ready – Works seamlessly with MCP-compatible AI clients (Claude, Cursor, etc.)

---

🚀 Project Overview

Traditional chatbots can answer questions but often lack access to user-specific data and external capabilities.

FinChat addresses this by providing an MCP server that exposes financial tools to AI agents. Instead of hardcoding every workflow, the AI agent can understand user requests, select the appropriate tool, execute it, and generate meaningful responses.

Example User Interaction:

User: "How much did I spend on groceries in July?"

Agent Workflow:
  User Request → AI Agent → MCP Tool Discovery → 
  get_spending_summary() → Financial Analysis → Response

---

🏗️ Architecture

         User Input
            |
            ▼
   MCP-Compatible AI Client
   (Claude / Cursor / Agent)
            |
            ▼
       MCP Protocol
            |
            ▼
    FinChat MCP Server
            |
    ┌───────┼───────┐
    ▼       ▼       ▼
Transactions Analytics Goals
    |       |       |
    └───────┼───────┘
            ▼
   Financial Data Storage
      (Synthetic JSON)

---

🔌 Why Model Context Protocol (MCP)?

MCP provides a standardized interface for AI applications to discover and interact with external tools.

Benefits:

• ✓ Standardized tool discovery and execution
• ✓ Structured tool inputs and outputs
• ✓ Separation between AI reasoning and application logic
• ✓ Reusable tools across different AI clients
• ✓ Easier development of agent-based applications

---

🧠 MCP Server Design

The project follows a clean separation-of-concerns architecture:

mcp_server.py          tools/
├─ Register tools      ├─ add_transactions.py
├─ Expose schemas      ├─ query_transactions.py
└─ Handle I/O          ├─ spending_summary.py
                       ├─ financial_insights.py
                       ├─ set_financial_goal.py
                       ├─ update_financial_goal.py
                       └─ get_goal_progress.py

This keeps the MCP layer independent from the underlying financial logic.

---

🛠️ Tech Stack

Category	Technology
Protocol	Model Context Protocol (MCP)
Framework	FastMCP
Language	Python 3.8+
Data Storage	JSON (development), SQLite (planned)
IDE	VS Code

---

🔌 Available MCP Tools

Transaction Management

add_transactions

Adds financial transactions into the system.

Example:

User: "Add a $50 grocery expense at Walmart today"

get_transactions

Retrieves stored financial transactions with filtering capabilities.

Example queries:

• "Show my transactions from July"
• "Show all restaurant expenses"

---

📊 Spending Analytics

get_spending_summary

Generates spending summaries and category-based analysis.

Example queries:

• "How much did I spend this month?"
• "Show my grocery spending in July"
• "Break down expenses by category"

get_financial_insights

Analyzes spending behavior and generates financial observations.

Example queries:

• "Where am I spending the most?"
• "What expenses can I reduce?"
• "Analyze my spending patterns"

---

🎯 Financial Goal Management

set_financial_goal

Creates new financial goals.

Example:

User: "I want to save $50,000 by 2028"

Stores:

• Goal name
• Target amount
• Current savings
• Target date

update_financial_goal

Updates an existing financial goal.

Example:

User: "I saved another $5,000 toward my savings goal"

get_goal_progress

Tracks progress toward financial goals.

Example queries:

• "How much progress have I made?"
• "How much do I need to save monthly?"

---

📂 Project Structure

FinChat/
│
├── mcp_server.py              # MCP server entry point
│
├── tools/                      # Business logic & calculations
│   ├── add_transactions.py
│   ├── query_transactions.py
│   ├── spending_summary.py
│   ├── financial_insights.py
│   ├── set_financial_goal.py
│   ├── update_financial_goal.py
│   └── get_goal_progress.py
│
├── data/                       # Data storage
│   ├── transactions.json
│   └── financial_goals.json
│
├── requirements.txt
├── pyproject.toml
└── README.md

---

⚙️ Installation & Setup

1. Clone the repository:

git clone <repository-url>
cd FinChat

2. Create and activate virtual environment:

Windows (PowerShell):

python -m venv .venv
.venv\Scripts\activate

macOS/Linux:

python -m venv .venv
source .venv/bin/activate

3. Install dependencies:

pip install -r requirements.txt

---

▶️ Running the MCP Server

python mcp_server.py

The MCP server runs using stdio transport and communicates with MCP-compatible AI clients.

---

💡 Quick Usage Example

Once the server is running, connect via an MCP client:

# Example: Query spending by category
user_message = "How much did I spend on groceries in July?"

# Agent discovers available tools → selects get_spending_summary
# → executes with filters → returns analysis

---

🔐 Data Privacy & Security

Current implementation (development only):

• ✓ Synthetic financial data only
• ✗ No real bank connections
• ✗ No personal financial records
• ✗ No external financial APIs

Production requirements:

• Secure authentication (OAuth 2.0)
• Encrypted data storage
• Database-level access control
• Banking API integrations
• Compliance & regulatory review

---

⚠️ Current Limitations

• Uses local JSON storage (single-user)
• Designed for demonstration purposes
• Does not connect to banking providers
• Does not provide regulated financial advice
• Requires manually provided transaction data

---

🔮 Future Improvements

• Replace JSON with SQLite/PostgreSQL
• Add multi-user support with authentication
• Integrate real banking APIs (Plaid, etc.)
• Build automated savings recommendations
• Add interactive web dashboard
• Implement advanced financial planning
• Add budget forecasting
• Generate monthly financial reports

---

👨‍💻 About This Project

Built as a hands-on exploration of:

• Model Context Protocol (MCP) architecture
• LLM tool integration and function calling
• AI agent design patterns
• Structured data interaction with AI systems

Learning Goals:

• Understand how AI agents discover and execute external tools
• Build production-ready MCP servers
• Design AI-ready application architectures
• Implement secure tool orchestration

---

📝 License

MIT License

---

Built as a portfolio project to demonstrate AI/ML capabilities and modern LLM application architecture.