π¦
io.github.justfsl50/expense-mcp
Personal Expense Tracker MCP Server β expenses, income, budgets & savings goals
0 installs
Trust: 37 β Low
Devtools
Ask AI about io.github.justfsl50/expense-mcp
Powered by Claude Β· Grounded in docs
I know everything about io.github.justfsl50/expense-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Loading tools...
Reviews
Documentation
π° 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.
