expense-tracker-mcp-server

Expense Tracker MCP Server

A powerful Model Context Protocol (MCP) server for tracking and managing personal expenses. This server integrates with Claude Desktop to provide seamless expense management through natural language interactions.

Features

🛠️ Tools

• add_expense: Add new expenses with flexible date parsing (supports "today", "yesterday", "Nov 27, 2025", etc.)
• list_expenses: List expenses with filtering by category, date range, and natural language date queries
• summarize_expenses: Get expense summaries by category with totals and percentages
• update_expense: Modify existing expense records
• delete_expense: Remove expense records by ID

📋 Resources

• expense://categories: Access predefined expense categories and subcategories from categories.json

✨ Key Capabilities

• Natural Language Date Support: Use phrases like "last week", "last month", "this year", "last 30 days"
• SQLite Database: Lightweight and efficient local storage
• Category Management: Pre-defined categories with subcategories for better organization
• Flexible Filtering: Filter expenses by date range, category, or specific criteria
• Rich Summaries: View spending patterns with category-wise breakdowns and percentages

Installation

Prerequisites

• Python 3.8 or higher
• uv package manager (recommended)
• Claude Desktop

Steps

1. Clone the repository

   git clone <your-repo-url>
   cd Expense-Tracker-MCP-Server

1. Install dependencies

Using uv (recommended): ``bash uv pip install -r requirements.txt ``

Or using pip: ``bash pip install -r requirements.txt ``

1. Install to Claude Desktop

   uv run fastmcp install claude-desktop main.py

Or manually add to your Claude Desktop config (~/.config/Claude/claude_desktop_config.json on Mac/Linux or %APPDATA%\Claude\claude_desktop_config.json on Windows):

   {
     "mcpServers": {
       "Expense Tracker Server": {
         "command": "uv",
         "args": [
           "run",
           "--with",
           "fastmcp",
           "fastmcp",
           "run",
           "/absolute/path/to/Expense-Tracker-MCP-Server/main.py"
         ]
       }
     }
   }

1. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the MCP server.

Usage

Once installed, you can interact with the Expense Tracker directly in Claude Desktop using natural language:

Adding Expenses

"Add an expense of $45.50 for groceries yesterday"
"I spent $20 on lunch today in the Food category"
"Add expense: $100, Transport, Fuel, Nov 25, 2025, note: Monthly fuel"

Listing Expenses

"Show me all expenses from last week"
"List my Food expenses from this month"
"Show expenses from last 30 days"

Summarizing Expenses

"Summarize my expenses for last month"
"Show category-wise breakdown for this year"
"Summarize Food expenses from last week"

Updating Expenses

"Update expense ID 5, change amount to $55.50"
"Change expense 3's category to Transport"

Deleting Expenses

"Delete expense with ID 7"

Database Schema

The server uses SQLite with the following schema:

CREATE TABLE expenses (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    date TEXT NOT NULL,
    amount REAL NOT NULL,
    category TEXT NOT NULL,
    subcategory TEXT,
    note TEXT
);

Categories

The server includes predefined categories in categories.json:

• Food (groceries, dining out, coffee, snacks, etc.)
• Transport (fuel, public transport, cab, parking, etc.)
• Housing (rent, maintenance, repairs, etc.)
• Utilities (electricity, water, internet, mobile, etc.)
• Health (medicines, doctor, insurance, fitness, etc.)
• Education (books, courses, online subscriptions, etc.)
• Entertainment (movies, streaming, games, etc.)
• Shopping (clothing, electronics, accessories, etc.)
• And many more...

You can customize categories by editing categories.json.

Development

Running Locally

uv run fastmcp dev main.py

Project Structure

Expense-Tracker-MCP-Server/
├── main.py                 # Main MCP server code
├── categories.json         # Expense categories and subcategories
├── requirements.txt        # Python dependencies
├── pyproject.toml         # Project metadata
├── expenses.db            # SQLite database (auto-created)
└── README.md              # This file

Requirements

• fastmcp>=2.0.0 - FastMCP framework for building MCP servers
• python-dateutil>=2.8.0 - Flexible date parsing

Troubleshooting

Server not showing in Claude Desktop

1. Ensure Claude Desktop is completely quit (not just closed)
2. Check the config file has correct absolute paths
3. Verify the command path to uv is correct
4. Restart Claude Desktop

Database issues

The expenses.db file is created automatically in the project directory. If you encounter issues:

• Delete expenses.db and restart the server
• Check file permissions

Date parsing errors

The server supports various date formats. If you encounter parsing errors:

• Use ISO format: "YYYY-MM-DD" (e.g., "2025-11-27")
• Use common formats: "Nov 27, 2025", "27th November 2025"
• Use relative dates: "today", "yesterday", "last week"

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - feel free to use this project for personal or commercial purposes.

Author

Created with FastMCP and Claude

Acknowledgments

• Built with FastMCP
• Powered by Model Context Protocol