io.github.justfsl50/expense-mcp

💰 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

# 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):

{
  "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

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

HTTP mode (remote / multi-client)

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:

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:

"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

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.