Expense Tracker MCP Server

# Expense Tracker MCP Server A Model Context Protocol (MCP) server for tracking personal expenses with SQLite database storage. This server integrates with Claude Desktop to provide expense management capabilities through natural language. ## Features - ✅ Add, update, and delete expenses - ✅ List expenses by date range - ✅ Summarize expenses by category - ✅ Flexible deletion by multiple criteria - ✅ Predefined expense categories - ✅ SQLite database for persistent storage ## Prerequisites - Python 3.10 or higher - [uv](https://github.com/astral-sh/uv) package manager - Claude Desktop app ## Installation ### 1. Install uv **Windows (PowerShell):** ```powershell powershell -c "irm https://astral.sh/uv/install.ps1 | iex" ``` **macOS/Linux:** ```bash curl -LsSf https://astral.sh/uv/install.sh | sh ``` ### 2. Initialize Project ```bash # Create and navigate to project directory mkdir expense-tracker-mcp-server cd expense-tracker-mcp-server # Initialize uv project uv init . ``` ### 3. Install Dependencies ```bash # Install required packages uv add fastmcp uv add sqlite3 # Usually comes with Python ``` ### 4. Create the Server Create a file named `main.py` and paste the expense tracker code (from the document provided). ### 5. Test the Server ```bash # Run the server uv run main.py ``` ## Configuration ### Claude Desktop Setup 1. Open Claude Desktop configuration file: - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` 2. Add the MCP server configuration: ```json { "mcpServers": { "expense-tracker": { "command": "uv", "args": [ "--directory", "C:/Users/YOUR_USERNAME/Desktop/expense-tracker-mcp-server", "run", "main.py" ] } } } ``` **Important**: Replace `C:/Users/YOUR_USERNAME/Desktop/expense-tracker-mcp-server` with your actual project path. 3. Restart Claude Desktop ## Usage Once configured, you can interact with the expense tracker through Claude using natural language: ### Add Expense ``` "Add an expense: $50 for groceries on 2024-12-14" "Log $25.50 spent on transport today with note 'Uber to office'" ``` ### List Expenses ``` "Show me all expenses from December 1 to December 14, 2024" "List my expenses for last week" ``` ### Update Expense ``` "Update expense ID 5 to $75" "Change the category of expense 3 to 'entertainment'" ``` ### Delete Expense ``` "Delete expense with ID 5" "Remove all food expenses from last week" "Delete expenses in the transport category" ``` ### Summarize Expenses ``` "Summarize my expenses by category for December 2024" "What's my total spending on food this month?" ``` ### View Categories ``` "What expense categories are available?" "Show me the list of categories" ``` ## Available Tools ### `add_expense` Add a new expense to the tracker. **Parameters:** - `date` (string): Date in YYYY-MM-DD format - `amount` (float): Expense amount - `category` (string): Expense category - `subcategory` (string, optional): Subcategory - `note` (string, optional): Additional notes ### `list_expenses` List all expenses within a date range. **Parameters:** - `start_date` (string): Start date (YYYY-MM-DD) - `end_date` (string): End date (YYYY-MM-DD) ### `update` Update an existing expense (only provided fields will be updated). **Parameters:** - `cid` (int): Expense ID to update - `date` (string, optional): New date - `amount` (float, optional): New amount - `category` (string, optional): New category - `subcategory` (string, optional): New subcategory - `note` (string, optional): New note ### `delete` Delete expenses based on various criteria. **Parameters:** - `id` (int, optional): Delete by ID - `date` (string, optional): Delete by date - `category` (string, optional): Delete by category - `subcategory` (string, optional): Delete by subcategory - `amount` (float, optional): Delete by amount - `note` (string, optional): Delete by note - `start_date` & `end_date` (strings, optional): Delete by date range ### `summarize` Get expense summaries grouped by category. **Parameters:** - `start_date` (string): Start date (YYYY-MM-DD) - `end_date` (string): End date (YYYY-MM-DD) - `category` (string, optional): Filter by specific category ## Available Resources ### `expense://categories` Returns the list of available expense categories in JSON format. ## Database Schema ```sql CREATE TABLE expenses ( id INTEGER PRIMARY KEY AUTOINCREMENT, date TEXT NOT NULL, amount REAL NOT NULL, category TEXT NOT NULL, subcategory TEXT DEFAULT '', note TEXT DEFAULT '' ); ``` ## File Structure ``` expense-tracker-mcp-server/ ├── main.py # MCP server code ├── expense.db # SQLite database (auto-created) ├── categories.json # Categories list (auto-created) ├── pyproject.toml # uv project configuration └── README.md # This file ``` ## Default Categories The server comes with these default categories: - food - transport - entertainment - utilities - healthcare You can modify `categories.json` to add or remove categories. ## Troubleshooting ### Server not appearing in Claude Desktop 1. Check the configuration file path is correct 2. Ensure the `command` path points to your project directory 3. Restart Claude Desktop completely 4. Check Claude Desktop logs for errors ### Database errors If you encounter database errors: ```bash # Delete the database to reset rm expense.db # Restart the server to recreate the database uv run main.py ``` ### Import errors ```bash # Reinstall dependencies uv sync ``` ## Development To modify the server: 1. Edit `main.py` 2. Test changes: `uv run main.py` 3. Restart Claude Desktop to load changes ## Contributing Contributions are welcome! Feel free to submit issues or pull requests. ## Support For issues related to: - **MCP Protocol**: [MCP Documentation](https://modelcontextprotocol.io) - **FastMCP**: [FastMCP GitHub](https://github.com/jlowin/fastmcp) - **Claude Desktop**: [Anthropic Support](https://support.anthropic.com)