Personal finance management CLI and MCP server
- Python 100%
|
David Wilson
fcb3147611
Relock to sigil 0.17.12 via sigil-wise/ledger 0.10.2; release v0.2.5
Now that sigil-wise v0.10.2 (sigil-http/json ^0.16) and sigil-ledger v0.10.2 (sigil-json ^0.16) are on the modern line, the socket/json ^0.14-vs-^0.16 deadlock is gone: deps update resolves the 0.17.12 runtime cleanly. Rebuilt -c release, embedded 0.17.12 confirmed, MCP initialize->tools/list handshake verified (5 tools). |
||
|---|---|---|
| scripts | Add QBO CSV/XLSX import to hledger journal format | |
| src/tally | Read mcp-server version from (app-version); bump to v0.2.2 | |
| test | Add QBO CSV/XLSX import to hledger journal format | |
| .gitignore | Refresh for sigil 0.14 ecosystem; bump to v0.2.0 | |
| dev-redirects.sgl | Modernize to sigil 0.17 / sigil-mcp 0.16.2 ecosystem | |
| package.sgl | Relock to sigil 0.17.12 via sigil-wise/ledger 0.10.2; release v0.2.5 | |
| README.md | Address all 7 code review findings | |
| sigil.lock | Relock to sigil 0.17.12 via sigil-wise/ledger 0.10.2; release v0.2.5 | |
tally
Personal finance management CLI and MCP server. Pulls transactions from Wise, categorizes them, writes to hledger journal files, and generates financial summaries.
Features
- Pull transactions from Wise API across all currency balances
- Map Wise transactions to hledger journal format with proper double-entry bookkeeping
- Deduplicate imports — safe to run repeatedly without double-counting
- Run hledger reports (balance, register, income statement)
- List uncategorized transactions for review
- Dual-mode: works as both a CLI tool and an MCP server for AI-assisted bookkeeping
CLI Usage
tally serve Start MCP server
tally pull [--since DATE] [--until DATE] [--profile TYPE]
Pull transactions from Wise
tally import [--journal FILE] [--since DATE] [--until DATE]
Pull and write to journal
tally balance [--profile TYPE] Show Wise balances
tally report [--journal FILE] [--type bal|reg|is] [QUERY]
Run hledger reports
tally categorize [--journal FILE] List uncategorized transactions
Examples
# Pull recent transactions
tally pull --since 2026年03月01日T00:00:00Z
# Pull transactions within a date range
tally pull --since 2026年01月01日T00:00:00Z --until 2026年03月31日T23:59:59Z
# Import transactions to journal with deduplication
tally import --journal finances.journal --since 2026年01月01日T00:00:00Z
# Check current Wise balances
tally balance
# Run a balance report
tally report --type bal assets
# Monthly income statement
tally report --type is
# List uncategorized transactions
tally categorize --journal finances.journal
MCP Server Tools
When running as an MCP server (tally serve), the following tools are available:
| Tool | Description |
|---|---|
tally/pull |
Pull recent transactions from Wise API |
tally/import |
Pull and import new transactions into journal |
tally/balance |
Show current Wise account balances |
tally/report |
Run hledger reports (bal, reg, is) |
tally/categorize |
List uncategorized transactions for review |
Configuration
Environment variables:
| Variable | Required | Description |
|---|---|---|
WISE_API_TOKEN |
Yes (for Wise operations) | Wise personal API token |
TALLY_JOURNAL |
No | Default journal file path (default: main.journal) |
TALLY_PROFILE |
No | Default Wise profile type: personal or business (default: personal) |
Account Mapping
Wise transactions are mapped to hledger accounts as follows:
- Wise balances:
assets:wise:{currency}(e.g.,assets:wise:eur,assets:wise:usd) - Debit transactions:
expenses:uncategorized(re-categorize after import) - Credit transactions:
income:uncategorized(re-categorize after import)
Each imported transaction includes the Wise reference number as both a transaction
code and a ref tag for deduplication.
Dependencies
- sigil-wise — Wise API client library
- sigil-ledger — hledger journal read/write
- sigil-mcp — MCP server framework
- hledger — required on PATH for report commands
Building
Requires a C toolchain. On Guix:
guix shell -m ../sigil/manifest.scm -- env CC=gcc sigil build --redirects dev-redirects.sgl
Testing
guix shell -m ../sigil/manifest.scm -- env CC=gcc sigil test --redirects dev-redirects.sgl
Note: tests require a lib symlink to the build output for dependency resolution:
ln -s build/dev/lib lib