# Finance Tracker MCP Server

AI-powered personal finance analysis through Claude AI using the Model Context Protocol (MCP).

![Finance Tracker Demo](screenshot.png)

## What This Does

This MCP server connects Claude AI to financial transaction data, enabling natural language queries about your finances:

- "Show me my spending this month"
- "Find all my subscriptions"
- "What were my top 10 expenses?"
- "Show spending trends for the last 3 months"
- "Search for all Starbucks transactions"
- "Check my budget: Dining $500, Shopping $300"

## Features

- **6 Financial Analysis Tools**
  - Monthly spending summaries
  - Subscription detection (recurring charges)
  - Budget tracking & alerts
  - Spending trend analysis
  - Top expenses ranking
  - Transaction search

- **Plaid Integration**
  - Connect to 10,000+ banks (sandbox mode for testing)
  - Real-time transaction data (when connected to real accounts)
  - Secure API access

- **Privacy First**
  - All data stays local on your machine
  - No external data storage
  - Encrypted API connections

## Quick Start

### Prerequisites

- Python 3.9 or higher
- Claude Desktop app
- Plaid account (free at https://dashboard.plaid.com)

### Installation

1. **Clone the repository**
```bash
   git clone https://github.com/yourusername/finance-plaid-mcp.git
   cd finance-plaid-mcp
```

2. **Create virtual environment**
```bash
   python -m venv venv
   
   # Activate it:
   # Windows:
   venv\Scripts\activate
   # Mac/Linux:
   source venv/bin/activate
```

3. **Install dependencies**
```bash
   pip install -r requirements.txt
```

4. **Set up Plaid API keys**
   
   Copy `.env.example` to `.env` and add your Plaid keys from https://dashboard.plaid.com
   
```bash
   PLAID_CLIENT_ID=your_client_id_here
   PLAID_SECRET=your_sandbox_secret_here
   PLAID_ENV=sandbox
   DATA_DIR=./data
```

5. **Generate sample data** (for testing)
```bash
   python generate_sample_data.py
```

6. **Configure Claude Desktop**
   
   Add this to your Claude Desktop config file:
   
   **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
   
   **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
   
```json
   {
     "mcpServers": {
       "finance-tracker": {
         "command": "python",
         "args": [
           "/FULL/PATH/TO/finance-plaid-mcp/src/server.py"
         ]
       }
     }
   }
```
   
   **Important:** Use the full absolute path to your project!

7. **Restart Claude Desktop**

8. **Test it!**
   
   In Claude, ask:
"Find all my subscriptions"

## 📁 Project Structure
finance-plaid-mcp/
├── src/
│   ├── server.py          # MCP server (main entry point)
│   ├── plaid_client.py    # Plaid API integration
│   ├── analyzer.py        # Transaction analysis logic
│   └── config.py          # Configuration & environment variables
├── data/
│   └── sample_transactions.json  # Generated test data
├── screenshot.png         # Demo screenshot
├── .env                   # Your API keys (NOT committed to git)
├── .env.example           # Template for API keys
├── .gitignore            # Prevents committing secrets
├── requirements.txt       # Python dependencies
└── README.md             # This file

## 🔧 Available Tools

Claude can call these tools when analyzing your finances:

| Tool | Description |
|------|-------------|
| `monthly_summary` | Get spending/income summary for any month |
| `find_subscriptions` | Detect recurring charges (Netflix, Spotify, etc.) |
| `spending_trends` | Analyze spending patterns over time |
| `budget_check` | Compare actual spending vs budget limits |
| `top_expenses` | Get largest expenses ranked |
| `search_transactions` | Search by merchant or category |

## 🏦 Connecting Real Bank Accounts

**Currently in Sandbox Mode** (test data only)

To connect real banks:

1. Switch to Development mode in Plaid dashboard
2. Update `.env`: `PLAID_ENV=development`
3. Implement Plaid Link UI (web interface for bank login)

**For portfolio/demo purposes, sandbox mode is recommended** to avoid exposing real financial data.

## 📊 Sample Output

**Finding Subscriptions:**
19 subscriptions found totaling $18,123/year
Top subscriptions:

Comcast Internet: $130.71/mo ($915 total)
Apple Store: $180.05/mo ($900 total)
Verizon Phone Bill: $110.75/mo ($886 total)
Electric Bill: $119.86/mo ($839 total)
Zara: $151.91/mo ($760 total)


**Monthly Summary:**
Monthly total: $1,510
Income: $5,000
Expenses: $3,490
Net: $1,510
Spending by category:

Groceries: $644
Shopping: $900
Utilities: $886
Dining: $450
Transportation: $380


## 🛠️ Tech Stack

- **Python 3.14**
- **MCP SDK** - Model Context Protocol
- **Plaid API** - Bank connection & transaction data
- **Pandas** - Data analysis
- **Claude AI** - Natural language interface

## 🔐 Security & Privacy

- ✅ API keys stored in `.env` (never committed)
- ✅ All data processed locally
- ✅ No external logging or analytics
- ✅ Plaid provides bank-level encryption

**⚠️ Important:** Never commit your `.env` file or API keys to GitHub!

## 🤝 Contributing

Contributions welcome! Feel free to:

- Report bugs
- Suggest features
- Submit pull requests

## 📝 License

MIT License

## 🙏 Acknowledgments

- Built with [Anthropic's MCP](https://modelcontextprotocol.io)
- Powered by [Plaid](https://plaid.com)


---

**⭐ If you found this helpful, please star the repo!**