finflow-mcp

Automatic personal finance tracker. It reads transaction notification emails from Gmail, extracts the numbers, and appends them to a Google Sheets ledger — on a schedule, without you opening anything.

finflow setup            # locale, timezone, base currency
finflow auth             # connect your own Google OAuth client
finflow sync             # creates the ledger, writes the first rows
finflow daemon install   # and then you can stop thinking about it

finflow status tells you whether it is still working.

Status: early development. The core is built and tested; it has not yet run for weeks against a real mailbox. See Honest limitations.

Two ways to run it

Autopilot (the point of the project). A per-OS scheduled job runs finflow daemon run-once and exits — launchd on macOS, a systemd user timer on Linux, Task Scheduler on Windows. There is no long-lived background process, which removes every memory-leak and stale-token class of bug and survives reboots for free.

MCP server. Connect it to an AI client (Claude Desktop, Claude Code) and ask about your spending, or drive a sync interactively. In this mode the server never calls an LLM — the connected client does the extraction and posts results back through the same validation and de-duplication the daemon uses.

// Claude Desktop config — check the current docs for the file location
{
  "mcpServers": {
    "finflow": { "command": "finflow-mcp" },
  },
}

Related MCP server: accounting-mcp-server

How an email becomes a row

Gmail search (short, language-agnostic query)
   └─ client-side scoring against every keyword pack   ← language support is free here
        └─ sanitise: mask cards/accounts, strip OTPs, truncate
             └─ extract
                  ├─ sender template        free, instant, offline, reproducible
                  ├─ Claude (optional)      opt-in, your own API key, cost-capped
                  └─ neither                parked in needsExtraction — never guessed
                       └─ validate (Zod) → categorise → de-duplicate → Sheets

Extraction is a strategy, so there is exactly one pipeline. The daemon and the MCP server differ only in which extractor is plugged in — "validation is identical on both paths" is a structural fact rather than something to keep re-checking.

Design commitments

Read-only against Gmail. Scopes are gmail.readonly and drive.file. No modify, send or delete scope is ever requested, and drive.file cannot see any file FinFlow did not create.

Integer money. Amounts are stored as integer minor units. There is no floating-point arithmetic anywhere on the ledger path, currency exponents are an explicit table (JPY is 0, KWD is 3), and an unknown currency is an error rather than an assumption of 2.

Ambiguity is refused, never guessed. Rp1.234 means different things in different locales. When the text and the configured locale cannot settle it, FinFlow reports PARSE_AMBIGUOUS instead of picking the likelier reading. In a ledger, a wrong number recorded silently is worse than an email that fails loudly.

Dates are Temporal, not milliseconds. Month boundaries are computed as PlainDate → startOfDay(timezone). March 2026 is 744 hours in Jakarta, 743 in New York and 745 in Berlin, and the tests assert exactly that.

Language support is free where it can be. Month names come from CLDR via a build-time codegen (72 languages, committed so runtime never depends on the user's ICU build); number separators come from Intl. Keyword scoring runs client-side, so adding a language costs nothing in API quota or query length.

Failures are visible. The daemon writes a heartbeat on every run — success or failure — and raises an OS notification once per failure streak, not once per failure. Silent failure is the worst possible outcome for an autopilot: you go on believing the ledger is complete while it quietly stops being so.

Nothing leaves the machine uninvited. Network egress is googleapis.com only, plus api.anthropic.com if you explicitly enable the Claude extractor. In that case only the sanitised body is sent — account numbers masked, one-time codes removed, raw text never.

Idempotency

The scheduler runs hourly over a 48-hour overlap window, so every email is seen many times. Identity is deliberately split:

• transactionId = hash of (source, sourceRef, occurrenceIndex) — which email, and it never changes

• contentHash = hash of the extracted values — what we read, and it may

The second row is why the two hashes are separate. Combined, a re-read that produced any difference would get a new id, miss the lookup, and append a duplicate — which with an hourly daemon is not a rare edge case.

Deleting a row in the sheet by hand is respected: a short ring of processed email ids stops the next sync from helpfully putting it back.

Configuration

~/.finflow/config.json, validated on every load.

Secrets live in ~/.finflow/.env (0600), never in config.json.

Commands

Honest limitations

• Parsing quality depends on sender templates, not on language. A BCA template does not help with Mandiri. The i18n work makes amounts and dates language-independent; it cannot make a bank's HTML layout universal. Expect the first week to lean on the Claude extractor if you enable it.

• Not supported, by choice: non-positional CJK numerals (二万五千), Japanese-era and Hijri calendars, currency conversion, and month names that are ambiguous across languages without a narrowing locale (listopad is November in Polish and October in Croatian). Each is reported, never guessed.

• You will occasionally need to re-authenticate — realistically only when you change your Google password, which revokes Gmail-scoped tokens and cannot be worked around.

• Accuracy is not 100%. The needs_review column and extraction_confidence exist so you can audit rather than trust blindly.

Threat model, briefly

Requirements

• Node.js >= 20

• Your own Google Cloud project — see docs/google-setup.md

• Optional: an Anthropic API key, only if you enable the Claude extractor

Development

npm install
npm run typecheck && npm run lint && npm test
npm run gen:month-names   # regenerate the CLDR month table (output is committed)

License

MIT