io.github.justfsl50/expense-mcp
Personal Expense Tracker MCP Server — expenses, income, budgets & savings goals
Open source Open in the app JSON README (API)
About
Personal Expense Tracker MCP Server — expenses, income, budgets & savings goals
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- justfsl50
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 1
- Last push
- 2026-03-04T12:02:55Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:18
- Updated
- 2026-08-29 04:00:18
- Origin id
io.github.justfsl50/expense-mcp
README
# 💰 expense-mcp
> Personal Expense Tracker as an MCP Server — works with Claude Desktop, Cursor, nanobot, Windsurf, and any MCP-compatible client.
[](https://python.org)
[](https://github.com/modelcontextprotocol/python-sdk)
[](LICENSE)
<!-- mcp-name: io.github.justfsl50/expense-mcp -->
---
## 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):
```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
```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:
```
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.