Personal Finance Agent

A local Model Context Protocol (MCP) server that gives an AI agent grounded, evidence-backed tools for managing your own finances: account balances, deterministic cash-flow projection, drift detection, recurring-charge onboarding, reconciliation, and Todoist reflection. The finance logic is deterministic and idempotent; the language model only interprets the results and helps you decide — it never invents a number. Every dollar figure the agent reports traces back to a row in your local database.

Design principles

• Deterministic and idempotent. All projections, drift checks, statement estimates, and reconciliation matches are pure functions of the stored data. Re-running a tool with the same inputs updates rows in place instead of duplicating them; nothing depends on model randomness.
• Grounding: every figure traces to a source row. Working cash traces to a balance snapshot, each obligation to its instance row, and projection endpoints are recomputable from the underlying instances. A dedicated verify_grounding tool is the gate that checks whether a headline number is allowed to be stated.
• Never auto-pays. Every write is guarded and preview-first. Reconciliation produces review evidence, not "paid" status. Marking an obligation paid takes an explicit confirmation plus a recorded transaction match. No tool moves money.
• Local SQLite is the source of truth. Cash-flow truth lives in obligation_instances in a local SQLite database. Discovered recurring charges are proposals until you apply them; they do not affect projections until then.
• Todoist writes are dry-run by default. The agent can stage review tasks in a durable outbox, but it only sends to Todoist when you explicitly enable live integration and configure a token and project. Off by default.

Install

Prerequisites:

• Python 3.11 or newer
• uv (Python package and project manager)
• git

git clone https://github.com/albeorla/personal-finance-agent.git
cd personal-finance-agent
uv sync

Verify the install by running the test suite (234 tests):

uv run --extra dev pytest -q

Setup

1. Create a .env from the template and fill in your own values:

   cp .env.example .env
   

   The server reads these environment variables (all optional except where your workflow needs them):

   • FINANCE_AGENT_ENV — path to a .env file the server loads at startup.
   • FINANCE_AGENT_DB_PATH — path to the SQLite database to use.
   • FINANCE_WORKING_ACCOUNT — substring matched against account names to pick your operating checking account (for example, its last four digits).
   • SIMPLEFIN_ACCESS_URL — SimpleFIN access URL for read-only bank sync.
   • TODOIST_API_TOKEN — Todoist API token for reading and (optionally) writing review tasks.
   • TODOIST_PROJECT_ID — Todoist project that holds finance review tasks.
   • TODOIST_WRITE_ENABLED — set to enable live Todoist write-back (off by default; the outbox stays dry-run until you turn this on).

2. Initialize the database schema (creates the local app tables):

   uv run python -m financial_agent.schema path/to/db.sqlite
   

Run

Start the stdio MCP server:

uv run financial-agent-mcp

Start the local inspector UI (a read-only developer surface):

uv run financial-agent-ui   # http://127.0.0.1:8765

The inspector shows balances, cash-flow projections, drift and review items, the onboarding queue, the latest background run's tool-call timeline, and raw telemetry. It is a debugging surface, not the product.

Register with Claude Code

Add a .mcp.json entry in the workspace where you want the agent available. Use the absolute path to your clone:

{
  "mcpServers": {
    "financial-agent": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/personal-finance-agent",
        "financial-agent-mcp"
      ],
      "env": {
        "FINANCE_AGENT_DB_PATH": "/absolute/path/to/your/db.sqlite",
        "FINANCE_WORKING_ACCOUNT": "1234"
      }
    }
  }
}

FINANCE_WORKING_ACCOUNT is optional; set it to a substring (for example the last four digits) that uniquely identifies your operating checking account so the agent leads with working cash instead of a debt-mixed total.

Tools

The server exposes its capabilities as MCP tools, grouped by area.

Status and daily digest

• get_finance_status — balances and totals, data-source freshness, deterministic cash-flow projections over requested windows, drift and guardrail findings, plus trace and result identifiers.
• get_daily_digest — a human-readable morning summary: working cash, multi-window cash-flow projection, upcoming obligations with running balances, drift and review items, recurring candidates, and a GREEN/YELLOW/RED guardrail status, each with provenance.

Income

• list_income_sources — configured income rules, schedule versions, review dates, and generated horizons.
• apply_income_source — create or update an income source and schedule version (after confirmation).
• generate_income_instances — create dated income instances from configured schedules, with extra closure dates as the import seam for payroll calendars.

Obligations

• apply_obligation_instances — store a durable obligation plus exact dated instances.
• list_obligations — list canonical obligations and their dated instances.
• list_obligation_review_candidates — obligation instances needing review (for example, an estimated amount whose review date has arrived).
• list_statement_input_estimates — card-spend estimates that feed future statement estimates without directly reducing checking cash flow.

Charge onboarding

New recurring charges are onboarded through an evidence-backed review queue rather than letting the model write obligation rows directly:

transactions -> discovered candidates -> review queue -> accepted policy
            -> canonical obligations/instances -> cash-flow/reconciliation

• scan_charge_onboarding_candidates — deterministic background discovery: groups related transactions by normalized merchant and account and proposes schedule, amount, cash-impact, and review policies as reviewable candidates. Never writes canonical obligations or moves cash flow.
• list_charge_onboarding_queue — candidates ordered by estimated monthly cash impact, weighted so real recurring obligations outrank variable discretionary spend and internal transfers.
• get_next_charge_onboarding_candidate — the single highest-priority unresolved candidate, for a one-at-a-time review walk.
• record_charge_onboarding_decision — record a decision: defer, reject, needs-more-evidence, in-review, accept, or reset.
• preview_charge_onboarding_apply — read-only preview of the canonical obligation and instances that applying would create.
• apply_charge_onboarding_candidate — guarded write that promotes an accepted candidate into a canonical obligation plus dated instances (idempotent; re-applying a window updates instances in place).

Detection classifies each candidate's cash-flow treatment from the account it lands on: a direct checking/savings outflow projects into the checking forecast; a card charge becomes a statement input that feeds statement estimates instead of reducing checking directly; highly variable non-utility card spend is deprioritized as discretionary; internal transfers and debt payments are deprioritized.

Statements

• aggregate_statement_inputs — group card-statement-input charges into the statement cycle that pays them.
• list_statement_cycles — each cycle with its input evidence and totals.
• recompute_statement_estimates — fill only unconfirmed statement estimates as a baseline plus rolled-up card inputs; an observed/portal amount is never overwritten.

Reconciliation

• reconcile_obligation_instances — match expected obligation instances to observed transactions by amount, date, and merchant. Conservative by default: matches are review evidence (not silently paid), unmatched past-grace instances become needs_review (not overdue), and card-statement inputs are skipped.
• list_matched_obligation_instances / list_unmatched_obligation_instances — inspect the results.
• list_reconciliation_review_items — matches awaiting confirmation.
• confirm_reconciliation_match — mark one obligation paid using its recorded transaction match (guarded; never auto-pays). unconfirm_reconciliation_match reverses it.

Drift

• detect_drift — find missing expected payments, stale estimates, amount changes, and unexpected recurring charges, ordered by severity.
• list_drift_findings — inspect recorded drift findings.

Todoist outbox

• preview_todoist_review_batch — render the day's review items into a Todoist task plus subtasks (read-only).
• enqueue_todoist_review_batch — record the batch in a durable, idempotent action outbox.
• execute_action_outbox — with no integration configured, simulate dry-run items and mark pending items as awaiting integration; only sends when Todoist write-back is explicitly enabled (idempotent: one task per outbox key).
• list_action_outbox — inspect the queue.
• sync_todoist / import_todoist_obligations — read the Todoist board and turn cashflow-candidate tasks into one-off obligations (idempotent by task id; a completed task sets a review date but is never auto-paid).
• list_todoist_sync_records / resolve_todoist_dedup_conflict — manage links and conflicts.

Background runner

• run_background_sync — orchestrate the whole pipeline (sync, scan, reconcile, detect drift, preview review batch) as one auditable run with an ordered operation-event log; a failing step is recorded and the run continues.
• get_background_run / list_background_runs — inspect run history and per-operation telemetry.
• sync_simplefin — pull live accounts, balances, and transactions from SimpleFIN into the local DB (idempotent upsert; read-only against SimpleFIN; supports incremental resume).

Memory

• write_finance_memory — store a correction, decision, or fact to recall.
• search_finance_memory — retrieve the most relevant memories under a context-control policy (similarity threshold, then top-k, then a token budget), reporting what each limit dropped. The embedding is a deterministic, dependency-free bag-of-words cosine — the one swap point for a real model later.

Grounding

• verify_grounding — check that every headline dollar figure in a status or digest result traces to a source row, and flag anything it cannot trace. The "is the agent allowed to say this number" gate.

Spending

• summarize_spending — report outflow spending by category, merchant, or month with totals, a month-over-month trend, and the transaction ids behind each bucket (rules-based categorizer, no LLM; transfers and income excluded by default).

Guardrails

• evaluate_guardrails — run the operating guardrails (configurable cash floor, drift threshold, window age, debt-payoff order); they also surface in get_finance_status.
• apply_guardrail_rules — seed the rules.
• list_guardrail_findings — inspect recorded evaluations.

A scheduled entry point (financial-agent-daily) runs the whole pipeline once under a file lock, for cron or launchd.

Status / disclaimer

This is a personal project and portfolio piece, not financial advice and not a product. No real financial data ships in this repository — the database is local, gitignored state that you create and populate yourself. Use it at your own risk and verify any number before acting on it.

License

MIT