Expense Tracker Server

An MCP (Model Context Protocol) server that lets AI assistants like Claude manage personal expenses — add, categorize, summarize, and budget — using a local SQLite database.

---

Overview

This server exposes a set of MCP tools that Claude (or any MCP-compatible client) can call to track your spending. All data is stored locally in a SQLite file — no cloud, no account required.

---

Features

• Add and manage expenses with categories, amounts, dates, and descriptions
• Filter and list expenses by date range or category
• Summarize spending by category or month
• Set per-category budgets and check remaining balances
• Export expenses to CSV
• Fully local — data stays on your machine

---

MCP Tools

Tool	Description	Key Parameters
add_expense	Record a new expense	amount, category, description, date, currency
list_expenses	List expenses with optional filters	category?, start_date?, end_date?, limit?
get_expense_summary	Aggregated totals grouped by category or month	group_by (category or month), start_date?, end_date?
update_expense	Edit an existing expense by ID	id, amount?, category?, description?, date?
delete_expense	Remove an expense by ID	id
set_budget	Set a monthly budget limit for a category	category, monthly_limit, currency?
get_budget_status	Compare budget limits vs actual spend	month? (defaults to current month)
export_expenses	Export expenses as a CSV string	start_date?, end_date?, category?

---

Project Structure

expense-tracker-mcp-server/
├── main.py             # MCP server entry point (all tools)
├── expenses.db         # SQLite database (auto-created on first run)
├── pyproject.toml      # Project metadata and dependencies
├── .venv/              # Virtual environment (created by uv)
└── readme.md

---

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Claude Desktop (to connect the MCP server)

---

Installation

# Clone the repo
git clone https://github.com/your-username/expense-tracker-mcp-server.git
cd expense-tracker-mcp-server

# Initialize the project and install dependencies
uv init
uv add fastmcp

This creates a .venv folder automatically inside the project directory.

---

Running the Server

fastmcp run main.py

The server starts and listens for MCP connections via stdio. The SQLite database (expenses.db) is created automatically on first run.

---

Connecting to Claude Desktop

Add the following to your Claude Desktop config file:

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

{
  "mcpServers": {
    "expense-tracker": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\Learning\\Expense-Tracker-MCP-Server",
        "run",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

Fully quit Claude Desktop (system tray → Quit) and reopen it. You should see the expense tracker tools available in the tools panel.

---

Example Prompts

Once connected to Claude, you can say:

• "Add a $45 expense for groceries at Whole Foods today"
• "Show me all food expenses from this month"
• "What did I spend the most on last month?"
• "Set a $300 monthly budget for dining out"
• "How much of my entertainment budget is left?"
• "Export all my expenses from March as CSV"

---

Development

# Run with MCP inspector for debugging
fastmcp dev inspector main.py

---

License

MIT