| name | toshl |
| description | Toshl Finance automation - sync data to local cache and generate monthly financial reports |
| context | inherit |
| allowed-tools | ["Bash","Read","Write","Edit","Grep","Glob"] |
| model | sonnet |
| user-invocable | true |
Toshl Financial Automation
Automate Toshl Finance data synchronization and monthly reporting with multi-entity financial strategy context (NS/DS/LW/VN + CCA extraction planning).
Data source: Toshl Finance API (via toshl MCP server)
Cache: Local CSV/JSON in toshl/data/ (git-tracked)
Reports: Markdown files in toshl/reports/
Commands
sync-data [start-month] [end-month]
Sync Toshl data to local CSV cache with reconciliation vs. prior state.
Usage:
/toshl sync-data # Current month MTD
/toshl sync-data 2026-03 # Single month
/toshl sync-data 2026-01 2026-04 # Inclusive month range
Implementation: Runs scripts/monthly_sync.py which calls the Toshl API directly (not via MCP — avoids token-limit spills). Stdlib only, no venv needed.
python3 toshl/scripts/monthly_sync.py --current
python3 toshl/scripts/monthly_sync.py 2026-03
python3 toshl/scripts/monthly_sync.py 2026-01 2026-04
python3 toshl/scripts/monthly_sync.py --current --json-report /tmp/reconcile.json
Script behavior:
- Reads
TOSHL_API_TOKEN from toshl/.env
- Paginates
/entries (per_page=200) for each month's date range
- Resolves account/category/tag IDs against
data/_{account,category,tag}_lookup.json
- Writes
data/{YYYY-MM}_entries.csv (denormalized, UTF-8, sorted date desc)
- Reconciles: prints rows/sum before → after and delta per month
- Idempotent — re-running the same month yields Δ=0
CSV format (denormalized, human-readable):
date,description,amount,currency,category,account,tags,type
2026-02-05,Groceries,-45.50,EUR,Food & Dining,Cash,shopping,expense
2026-02-10,Freelance Income,2500.00,EUR,Consulting,Cash,revenue,income
When to use MCP vs. this script:
- Script (
monthly_sync.py): for bulk backfill, monthly ritual, reconciliation. Always preferred for writing CSVs.
- MCP tools (
mcp__toshl__*): for live querying during analysis ("what did I spend on X?"). Never use for bulk export — token-limit spills on months >40 entries.
monthly-report
Generate markdown financial report for specified month. Auto-triggers sync-data first.
Usage:
/toshl monthly-report 2026-02
Workflow:
- Validate month format (YYYY-MM)
- Auto-run
/toshl sync-data {YYYY-MM} first (cache refresh)
- Read CSV entries from
data/{YYYY-MM}_entries.csv
- Parse and aggregate:
- Separate expenses (amount < 0) vs revenue (amount > 0)
- Group by category name (from CSV), sum amounts
- Calculate percentages of total
- Sort by amount descending
- Categories are dynamic from Toshl (no static mapping)
- Calculate summary metrics:
- Total expenses, total revenue, net
- Compare against targets
- Determine status (✅/⚠️/❌)
- Generate markdown report using template from reference.md
- Write to
reports/{YYYY-MM}.md
- Display summary to user
Status indicators:
- ✅ On target: Expenses ≤€4,000 AND Revenue ≥€7,500
- ⚠️ Within 10%: Expenses ≤€4,400 OR Revenue ≥€6,750
- ❌ Over/under: Expenses >€4,400 OR Revenue <€6,750
Implementation:
- Ensure
reports/ directory exists
- Use Write tool for report generation
- Format amounts as EUR with thousand separators, no decimals
- Round percentages to 1 decimal place
Financial Strategy Context
Entity structure:
- NS (Nosetalgy): Holding company
- DS (Digital Stoic): CTO-as-Service (100% NS)
- LW (Livarot): Whisky strategy (100% NS)
- VN (Villa Nara): Regenerative agriculture (49% NS)
Targets:
- Liquid reserves: €120K (24-month runway)
- Monthly burn: <€4K
- Net income: €90K/year (€7,500/mo avg)
CCA (compte courant d'associé): Currently ~€100K balance. Monthly reports track personal expenses to plan CCA extraction from entities.
Next Steps
Phase 2 (future):
- Entity breakdown in reports (personal vs NS/DS/LW/VN)
- CCA extraction recommendations
- Burn rate trends (3-6 month rolling)
- Non-Toshl data overlay (investments, loans)
See reference.md for account/category mappings and report template.
