💰 FinanceFlow

Your Personal Finance Analyzer - 100% Offline, 100% Private, 100% Yours

Built on NitroStack, Codescope exposes analysis results as MCP tools and renders interactive visualizations via built-in widgets.

---

🚀 The Problem

You download your bank statement. It contains your salary, rent, food expenses, medical bills, and every financial decision you've made. Then you upload it to some AI service. Where does it go? Who sees it? How long is it stored?

And then you get hit with the bill - $20/month for Mint, $15/month for YNAB, $10/month for Copilot Money... $540/year just to understand your own money.

✨ The Solution

FinanceFlow is an MCP (Model Context Protocol) server that analyzes your bank transactions entirely on your machine. No cloud. No API keys. No data leaving your computer. No monthly subscriptions. Just pure, private financial intelligence.

🔒 Your transactions never leave your computer. Period.

💰 Stop paying $500+/year for SaaS finance tools. FinanceFlow is free forever.

---

🎯 What It Does

FinanceFlow transforms your bank CSV into actionable financial insights:

• 📊 Detect Subscriptions - Find all recurring charges automatically
• 💸 Find Unused Subscriptions - Discover money you're wasting
• 📈 Price Increase Alerts - Catch subscription price hikes
• 🔄 Duplicate Detection - Find billing errors and double charges
• 📉 Spending Trends - Analyze your spending patterns over time
• 🇮🇳 Tax Deductions - Indian tax rules (Section 80C, 80D, 80TTA, etc.)
• 🎯 Savings Goals - Simulate and plan your savings targets
• 📋 Beautiful Reports - Generate HTML dashboards with D3.js charts
• 🔍 Person Search - Track money sent to specific people

---

🛡️ Privacy First

Feature	FinanceFlow	Cloud AI Services
Data Location	Your computer only	Unknown servers
API Key Required	❌ No	✅ Yes
Data Retention	Never stored	Indefinitely
Third-party Access	None	Unknown
Offline Capable	✅ Yes	❌ No
Cost	Free forever	$20-50/month

---

📦 Installation

Prerequisites

• Node.js 18+ installed
• NitroStack Studio (recommended) or any MCP client

Quick Start

# Clone the repository
git clone https://github.com/yourusername/financeflow.git
cd financeflow

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm run dev

That's it! No API keys, no configuration, no cloud setup.

---

🎬 Demo

Watch FinanceFlow in action:

# 1. Start the server
npm run dev

# 2. Open NitroStack Studio
# 3. Connect to the running server
# 4. Try these prompts:

Example Prompts

Import my bank statement from fixtures/indian-bank-statement.csv

Detect all my subscriptions

Find unused subscriptions for the last 2 months

Find tax deductions for 2026

Can I save ₹100,000 in 4 months to buy a MacBook?

Search all transactions with Rahul

Search all transactions with Priya

Generate a savings report and save it to /tmp/savings-report.html

---

🛠️ Tools (13 Total)

FinanceFlow provides 13 powerful MCP tools:

📊 Analysis Tools

Tool	Description
import-transactions	Import CSV and get basic statistics
categorize-transactions	Group transactions by category
detect-subscriptions	Find all recurring subscription charges
find-unused-subscriptions	Detect subscriptions you're not using
detect-price-increases	Catch subscription price hikes
find-duplicate-charges	Find billing errors and duplicates
analyze-spending-trends	Track spending patterns over time

💰 Optimization Tools

Tool	Description
find-tax-deductions	Find Indian tax deductions (80C, 80D, 80TTA, etc.)
simulate-savings-goal	Simulate savings goal feasibility

📄 Report Tools

Tool	Description
generate-savings-report	Generate HTML savings dashboard
generate-budget-report	Generate monthly budget breakdown
validate-csv-format	Validate CSV structure

🔍 Search Tools

Tool	Description
search-transactions-by-person	Search transactions by person name

---

📋 CSV Format

FinanceFlow accepts CSV files with these columns (auto-detected):

Date,Merchant,Amount,Category,Description
2026-01-01,TechCorp India Pvt Ltd,50000,Income,Monthly Salary
2026-01-05,Swiggy,345,Food,Food Delivery
2026-01-10,Netflix,649,Entertainment,Subscription

Flexible Column Detection:

• Date: Date, Transaction Date, Posting Date
• Merchant: Merchant, Vendor, Payee, Name
• Amount: Amount, Debit, Credit, Total
• Category: Category, Type, Group
• Description: Description, Memo, Notes

---

🇮🇳 Indian Tax Deductions

FinanceFlow supports comprehensive Indian tax deduction detection:

• Section 80C - Life Insurance, PPF, ELSS, Tuition fees (up to ₹1.5 lakh)
• Section 80D - Health Insurance Premium (₹25,000 for self, ₹50,000 for senior citizens)
• Section 80TTA - Savings Account Interest (up to ₹10,000)
• Section 24(b) - Home Loan Interest (up to ₹2 lakh)
• Section 80G - Charitable Donations (50% or 100% deduction)
• Section 80E - Education Loan Interest (no upper limit)
• Section 80CCD(1B) - NPS Additional Contribution (₹50,000)
• Section 80DDB - Medical Treatment for Specified Diseases
• Business Expenses - Software, tools, and work-from-home expenses
• HRA Exemption - House Rent Allowance (not in bank statement, but suggested)

---

📊 Sample Output

Subscription Detection

✅ Active subscriptions: 17
✅ Unused subscriptions: 2
✅ Price increases: 1

Unused:
  - Daily Hunt: ₹99 | Wasted: ₹396
  - Duolingo India: ₹199 | Wasted: ₹398

Price Increase:
  - Spotify India: ₹119 → ₹199 (67.2%)

Tax Deductions (India)

✅ Total deductions: ₹6,490
✅ Estimated savings: ₹324.50

Categories:
  - Section 80TTA - Savings Account Interest: ₹2,700
  - Business Expenses - Software & Tools: ₹3,790

Savings Goal Simulation

Goal: Buy MacBook (₹100,000 in 4 months)
✅ Possible: Yes
✅ Monthly needed: ₹25,000
✅ Current disposable: ₹28,773
✅ Gap: ₹0

Person Search

Person: Rahul
✅ Total transactions: 13
✅ Total amount: ₹4,250
✅ Average: ₹326.92

Person: Priya
✅ Total transactions: 23
✅ Total amount: ₹3,443
✅ Average: ₹149.70

---

🎨 Dashboard Widget

FinanceFlow includes a beautiful dashboard widget that displays:

• 📊 Summary cards (income, expenses, potential savings)
• 💳 Active subscriptions with amount badges
• ⚠️ Unused subscription alerts (red warning)
• 📈 Price increase badges (orange "↑60%")
• 💰 Tax deductions found count
• 🎯 Goal progress bar
• 🖱️ Click cards for detailed views

---

📄 HTML Reports

Generate professional HTML reports with:

• Savings Report: Category pie charts, unused subscriptions, price increases, duplicates, tax deductions, goal tracker
• Budget Report: Income vs expenses bar charts, category breakdown, top merchants, tax deductions summary

Reports use D3.js for beautiful, interactive charts.

---

🔧 Technical Details

Architecture

┌─────────────────────────────────────┐
│   MCP Client (NitroStack Studio)    │
└──────────────┬──────────────────────┘
               │
┌──────────────▼──────────────────────┐
│      FinanceFlow MCP Server         │
├─────────────────────────────────────┤
│  Analyzer Module                    │
│  ├─ TransactionService              │
│  └─ AnalyzerTools (7 tools)         │
│                                     │
│  Optimizer Module                   │
│  ├─ OptimizerService                │
│  └─ OptimizerTools (2 tools)        │
│                                     │
│  Report Tools (3 tools)             │
│  Search Tools (1 tool)              │
└─────────────────────────────────────┘

Tech Stack

• Runtime: Node.js 18+
• Language: TypeScript 5.3
• Framework: NitroStack
• Protocol: MCP (Model Context Protocol)
• Charts: D3.js v7
• Validation: Zod

---

🚀 Usage with NitroStack Studio

1. Download NitroStack Studio: nitrostack.ai/studio
2. Start FinanceFlow: npm run dev
3. Connect: NitroStack auto-detects the running server
4. Chat: Use natural language to analyze your finances

---

📝 Example Workflow

# 1. Export your bank statement as CSV
# 2. Start FinanceFlow
npm run dev

# 3. In NitroStack Studio, ask:
"Import my bank statement from ~/Downloads/statement.csv"
"Detect all my subscriptions"
"Find unused subscriptions"
"Generate a savings report"

# 4. Open the generated HTML report
open /tmp/savings-report.html

---

🤝 Contributing

Contributions are welcome! Areas for improvement:

• 🏦 Support more bank CSV formats
• 📊 Add more chart types
• 🎨 Enhance dashboard widget
• 🧪 Add more test cases
• 🌍 Add support for other countries' tax rules

---

📄 License

MIT License - feel free to use this project however you want.

---

🙏 Built With

• NitroStack - The MCP framework that makes this possible
• Model Context Protocol - The standard for AI-tool communication
• D3.js - Beautiful data visualization

---

💬 Community

• Discord: Join our community
• Twitter: @nitrostack
• GitHub: Report issues

---

⭐ Star History

If FinanceFlow helps you take control of your finances privately, consider giving it a star!

---

🔐 Security

• ✅ No data leaves your machine
• ✅ No external API calls
• ✅ No telemetry or analytics
• ✅ Open source - audit the code yourself
• ✅ Runs entirely offline

---

🎯 Who Is This For?

• Privacy-conscious individuals who want financial insights without compromising data
• Developers who want to build on top of a solid MCP foundation
• Indian users looking for tax deduction detection
• Anyone tired of subscription services eating their money
• Freelancers tracking business expenses
• Families managing shared finances

---

🚦 Quick Commands

npm run dev          # Start development server
npm run build        # Build for production
npm start            # Run production server
npm run widget       # Widget development

---

🔗 Links

• NitroStack Documentation
• NitroStudio
• GitHub

Made with ❤️ for privacy-conscious finance enthusiasts