Expense Tracker (MCP)

A single-user, PKR-only personal expense tracker exposed over MCP, so an agent is the primary interface. Log spending in one sentence — "4500 groceries at Imtiaz" — and ask for totals in another.

Storage is SQLite, embedded in the server process. There is no separate database container to run.

Design notes

• Amounts are integer paisa in storage; rupees are only used at the tool boundary.
• Only amount is required to log an expense. The date defaults to today, and the category is inferred from previous expenses at the same merchant.
• Categories are a fixed list (list_categories) so spelling can't fragment your reports.
• Deletes are soft — undo_last() restores.
• Duplicates warn, they don't block. An identical amount/merchant/date returns a possible_duplicate id and saves anyway.
• Recurring expenses post themselves on the first tool call after their day passes, tagged recurring. Nothing is scheduled and nothing double-posts.
• Payday is the 1st, so every reporting period is a plain calendar month.

Run it

The server speaks streamable HTTP at /mcp. It runs as a long-lived container, not one spawned per session.

docker compose up -d --build

That publishes http://127.0.0.1:8000/mcp and restarts with Docker.

docker compose logs -f     # follow
docker compose down        # stop

OpenClaw MCP config

{
  "mcpServers": {
    "expense-tracker": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

Security

The endpoint has no authentication — anything that can reach the port can read and edit the ledger. Two things keep that contained, and both matter:

• Compose publishes on 127.0.0.1 only, so the port is not on your network. Don't change that to 0.0.0.0 without putting auth in front of it.
• DNS-rebinding protection is on, so a browser page can't quietly drive the server.

If you publish on a host port other than 8000, requests fail with HTTP 421 Misdirected Request — the Host header no longer matches the allowlist. Set EXPENSE_TRACKER_ALLOWED_HOSTS to match, e.g. localhost:9000,127.0.0.1:9000.

stdio instead

Still supported, for debugging or a per-session launch:

docker run -i --rm -e EXPENSE_TRACKER_TRANSPORT=stdio \
  -v "$PWD/data:/data" -v "$PWD/backups:/backups" expense-tracker:latest

-i is required and -t must not be passed — under stdio a TTY corrupts the JSON-RPC framing.

Data and backups

Host	Container	Contents
./data	/data	live expenses.db
./backups	/backups	daily VACUUM INTO snapshots, last 14 kept

Both are gitignored. A snapshot is taken on the first tool call of each day, and backup_now() forces one.

Both directories live inside this project, so deleting it deletes the history and the backups. If this data comes to matter, sync ./backups somewhere off-machine.

If SQLite locking misbehaves over the Docker Desktop bind mount, set EXPENSE_TRACKER_JOURNAL=DELETE.

Environment

Variable	Default (container)
EXPENSE_TRACKER_TRANSPORT	http (or stdio)
EXPENSE_TRACKER_HOST	0.0.0.0 (127.0.0.1 outside Docker)
EXPENSE_TRACKER_PORT	8000
EXPENSE_TRACKER_ALLOWED_HOSTS	localhost:8000,127.0.0.1:8000
EXPENSE_TRACKER_DB	/data/expenses.db
EXPENSE_TRACKER_BACKUP_DIR	/backups
EXPENSE_TRACKER_JOURNAL	WAL
TZ	Asia/Karachi

TZ matters: on UTC the container dates anything logged after 7pm PKT to the previous day, skewing daily totals and month boundaries.

Tools

Write — add_expense, add_expenses, update_expense, update_last, delete_expense, undo_last

Read — list_categories, query_expenses, summarize, search_expenses

Budgets & recurring — set_budget, budget_status, add_recurring, list_recurring, delete_recurring

Maintenance — backup_now

query_expenses defaults to the current month and caps at 50 rows. For totals, use summarize — it aggregates in SQL rather than returning rows to be added up.

Development

uv sync --group dev && uv run pytest

Run the server outside Docker with uv run expense-tracker — HTTP on 127.0.0.1:8000, against ./data/expenses.db.

The suite covers both transports: a real MCP client over HTTP against a booted server, and a stdio startup that must leave stdout completely empty (under stdio, stdout carries the protocol, so a stray print() corrupts it — log to stderr only).