💰 expense-mcp

Personal Expense Tracker as an MCP Server — works with Claude Desktop, Cursor, nanobot, Windsurf, and any MCP-compatible client.

Features

📝 Track expenses & income with categories and descriptions
📊 Spending summaries — today, week, month, year
💳 Budget management — set limits per category, get alerts at 80%/100%
🎯 Savings goals — create goals, track progress with visual bars
📈 Spending insights — top categories, daily averages, biggest days
🗑️ Safe deletion — Pydantic-based elicitation for confirmation
🔄 Dual transport — stdio (local) + streamable HTTP (remote)

Install

bash

# with uv (recommended)
uv pip install git+https://github.com/justfsl50/expense-mcp.git

# with pip
pip install git+https://github.com/justfsl50/expense-mcp.git

# from source
git clone https://github.com/justfsl50/expense-mcp.git
cd expense-mcp
pip install -e .

Quick Start

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

config.json

{
  "mcpServers": {
    "expense-mcp": {
      "command": "uv",
      "args": ["run", "expense-mcp"],
      "env": {
        "DATABASE_URL": "sqlite:///expenses.db",
        "CURRENCY": "₹",
        "DEFAULT_USER": "me"
      }
    }
  }
}

Cursor / Windsurf

Same config — paste into MCP settings under the respective app.

nanobot

config.json

{
  "mcp": {
    "servers": [{
      "name": "expense-mcp",
      "command": "uv run expense-mcp"
    }]
  }
}

HTTP mode (remote / multi-client)

bash

python server.py http
# Server runs at http://127.0.0.1:8000/mcp

Environment Variables

Variable	Default	Description
`DATABASE_URL`	`sqlite:///expenses.db`	SQLite or PostgreSQL URL
`CURRENCY`	`₹`	Currency symbol
`DEFAULT_USER`	`default`	User ID for multi-user setups

PostgreSQL example:

Code

DATABASE_URL=postgresql://user:pass@localhost:5432/expenses

Tools

Tool	Description	Read-only
`expense_add`	Save expense or income	❌
`expense_search`	Filter by text, date, category, amount	✅
`expense_summary`	today / week / month / year totals	✅
`expense_delete`	Delete with Pydantic confirmation prompt	❌
`expense_insights`	Spending patterns and top categories	✅
`budget_set`	Set monthly category budget	❌
`budget_list`	View budgets with usage %	✅
`goal_create`	Create savings goal	❌
`goal_update`	Add money toward goal	❌
`goal_list`	View goals with progress bars	✅

Resources

URI	Description
`expense://summary/month`	Current month summary
`expense://budgets/current`	This month's budgets
`expense://goals/all`	All savings goals

Prompts

Prompt	Title	Description
`monthly_review`	Monthly Review	Start a full month spending review
`budget_setup`	Budget Setup	Auto-suggest budgets from history
`savings_plan`	Savings Plan	Create a plan for a savings goal

Usage Examples

Just talk naturally in any MCP client:

Code

"spent 500 on groceries"
"show food expenses this week"
"how much did I spend last month?"
"set food budget to 5000"
"am I within budget?"
"save 1000 toward my iPhone goal"
"give me spending insights"
"delete expense #12"

Architecture

MCP SDK v1.26.0 with FastMCP + json_response=True
Typed lifespan — DB engine managed via AppContext dataclass
SQLAlchemy 2.0 — DeclarativeBase, sessionmaker
Pydantic v2 — input validation, elicitation schemas
Tool annotations — readOnlyHint, destructiveHint, idempotentHint
Context logging — ctx.info(), ctx.warning() in tools

Database Schema

Code

expenses  — id, user_id, amount, category, description, type, date, source, created_at
budgets   — id, user_id, category, amount, month
goals     — id, user_id, name, target, saved, deadline

License

MIT — free to use, modify, and distribute.