Rahul4112002/Expense-Tracker-MCP-Server-Local-

Expense Tracker MCP Server (Local)

A FastMCP-based expense tracking server that enables AI assistants to add, list, and summarize personal expenses stored in a local SQLite database with category management.

Features

• 💰 Add Expenses: Record transactions with date, amount, category, subcategory, and notes
• 📊 List Expenses: View all expenses within a date range
• 📈 Summarize: Get category-wise spending summaries for any period
• 🏷️ Categories Resource: Access 20+ predefined expense categories with subcategories
• 💾 Local SQLite Storage: All data stored locally in expenses.db
• 🔧 FastMCP Integration: Seamless integration with Claude Desktop and other MCP clients

Installation

Prerequisites

• Python 3.12+
• uv package manager
• Claude Desktop (for MCP integration)

Setup

1. Clone the repository:

git clone https://github.com/Rahul4112002/Expense-Tracker-MCP-Server-Local-.git
cd expense-tracker-mcp-server

2. Install dependencies (handled automatically by uv):

uv sync

3. Configure Claude Desktop:

Edit your Claude Desktop config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "ExpenseTracker": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/absolute/path/to/expense-tracker-mcp-server/main.py"
      ],
      "env": {},
      "transport": "stdio"
    }
  }
}

Note for Windows users: Use forward slashes in paths and provide the full path to uv.exe:

{
  "mcpServers": {
    "ExpenseTracker": {
      "command": "D:/Python/Scripts/uv.exe",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "D:/AI/MCP/expense-tracker-mcp-server/main.py"
      ],
      "env": {},
      "transport": "stdio"
    }
  }
}

4. Restart Claude Desktop completely (check system tray to ensure it's fully closed)

Usage

Once configured, you can interact with the expense tracker through Claude Desktop using natural language:

Add an Expense

Add an expense: $45.50 for groceries on 2025-11-13

List Expenses

Show me all expenses from 2025-11-01 to 2025-11-13

Get Summary

Summarize my spending by category from 2025-11-01 to 2025-11-13

View Categories

What expense categories are available?

Available Tools

add_expense

Add a new expense entry to the database.

Parameters:

• date (string, required): Date in YYYY-MM-DD format
• amount (float, required): Expense amount
• category (string, required): Expense category
• subcategory (string, optional): Subcategory
• note (string, optional): Additional notes

Returns: {"status": "ok", "id": <expense_id>}

list_expenses

List expense entries within an inclusive date range.

Parameters:

• start_date (string, required): Start date (YYYY-MM-DD)
• end_date (string, required): End date (YYYY-MM-DD)

Returns: List of expense dictionaries

summarize

Summarize expenses by category within a date range.

Parameters:

• start_date (string, required): Start date (YYYY-MM-DD)
• end_date (string, required): End date (YYYY-MM-DD)
• category (string, optional): Filter by specific category

Returns: List of category summaries with total amounts

Available Categories

The server includes 20 predefined expense categories:

• 🍔 food - Groceries, dining, coffee, snacks
• 🚗 transport - Fuel, public transport, cabs, parking
• 🏠 housing - Rent, maintenance, repairs
• ⚡ utilities - Electricity, water, internet, mobile
• 🏥 health - Medicines, doctor visits, fitness
• 📚 education - Books, courses, subscriptions
• 👨‍👩‍👧‍👦 family_kids - School fees, daycare, clothes
• 🎬 entertainment - Movies, streaming, games
• 🛍️ shopping - Clothing, electronics, appliances
• 💳 subscriptions - SaaS, cloud services, streaming
• 💅 personal_care - Salon, grooming, cosmetics
• 🎁 gifts_donations - Gifts, charity, festivals
• 💰 finance_fees - Bank charges, interest, fees
• 💼 business - Software, hosting, marketing
• ✈️ travel - Flights, hotels, visa
• 🏡 home - Household supplies, repairs
• 🐾 pet - Food, vet, grooming
• 📄 taxes - Income tax, GST, filing fees
• 📊 investments - Mutual funds, stocks, crypto
• 📦 misc - Uncategorized expenses

Each category has multiple subcategories defined in categories.json.

Database Schema

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 ''
)

Development

Run the server standalone:

uv run --with fastmcp fastmcp run main.py

Modify categories:

Edit categories.json to add/modify expense categories and subcategories.

Files Structure

expense-tracker-mcp-server/
├── main.py              # Main MCP server code
├── pyproject.toml       # Project dependencies
├── categories.json      # Expense categories definition
├── expenses.db          # SQLite database (auto-created)
├── README.md           # This file
└── .venv/              # Virtual environment (auto-created)

Troubleshooting

Server not appearing in Claude Desktop

1. Verify config path: Ensure you're editing the correct claude_desktop_config.json
2. Check path format: Use forward slashes / instead of backslashes \
3. Use absolute paths: Provide full paths to both uv and main.py
4. Restart completely: Close Claude Desktop from system tray before reopening
5. Check logs: Look for errors in Claude Desktop logs

Finding uv path (Windows):

where uv

Testing the server:

uv run --with fastmcp fastmcp run main.py

If the server starts and shows "ExpenseTracker" in the banner, the server code is working.

License

MIT

Author

Created by Rahul

Contributing

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