finance-plaid-mcp

# Finance Tracker MCP Server AI-powered personal finance analysis through Claude AI using the Model Context Protocol (MCP).  ## 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!**