Expense MCP Server

💰 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

PostgreSQL example:

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

---

Tools

Resources

Prompts

---

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.