💰 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
AppContextdataclass - 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.