NavFi MCP server

get_financial_snapshotRead

Compact overview: accounts, credit cards (incl. rewards rates per category), plan summary, upcoming week, goals. Use for quick balance / debt / "how am I doing" / "best card for X" questions.

get_upcoming_eventsRead

Plan events between two dates (income, bills, card payments, savings, variable spend), each with the event_id that mark_turn_done takes. Prefer narrow windows for detail.

get_shortfall_diagnosticsRead

Diagnose the current plan shortfall (affected periods, skippable spending, postponable bills, pausable savings). Only call if plan has a shortfall.

No arguments.

get_spending_summaryRead

Aggregated spending in a date window: total, by category (top 8), top merchants (top 5). Does not return individual transactions.

get_transactionsRead

Individual transaction rows in a date window. Filter by category, merchant, amount range, direction. Use for "did I spend at X?" / "show recent grocery charges". Use get_spending_summary for totals.

get_projected_balanceRead

Plan-projected end-of-day balances on a specific date: per-account cash, per-card debt, totals. Use for "what will I have on Aug 1?" / "how much cash on payday?".

get_goal_progressRead

Goal progress + plan-based ETA: current vs target, projected arrival date or end-of-horizon shortfall. Use for "how am I doing on emergency fund" / "when will I hit my vacation goal".

list_categoriesRead

Spending categories, such as FOOD_AND_DRINK, with the ids other tools take. kind is expense, income, transfer or cc_payment.

No arguments.

list_accountsRead

The user's accounts and credit cards with their ids and current balances. A card balance is what is owed. manual means added by hand in NavFi rather than linked to a bank.

No arguments.

list_billsRead

The user's recurring bills with their ids: amount, frequency, next due date, category, and the account each is paid from. contributes_to_account_id set means the bill is a transfer into that account (money the user keeps), not spending. processing true means NavFi is still detecting bills from a newly linked bank, so the list may be incomplete.

No arguments.

list_incomeRead

The user's income sources with their ids: amount per paycheck, frequency, the next pay date and the checking account it lands in. processing true means NavFi is still detecting income from a newly linked bank, so the list may be incomplete.

No arguments.

get_weekly_budgetRead

The route's spending budget by category for the week that contains a date (default today): allocated, spent so far, planned purchases and remaining. This answers "how much can I spend on X this week". A category that is not listed has no budget that week.

get_route_statusRead

The route's state. generation_status is completed, generating, failed, timed_out or no_plan. A route takes minutes to calculate; poll this while it is generating.

No arguments.

get_route_healthRead

Route Health: whether the route still matches what happened. verdict is on_track, ahead, absorbed (drift the route absorbs), soft_rerun or strong_rerun (a reroute is advised) or strong_rerun_stale (the route is old). rerun_recommendation is none, optional, soft or strong. reason is a sentence to pass on. For whether a route exists or is still generating, use get_route_status.

No arguments.

get_readinessRead

Pre-Flight Check: whether NavFi has the data it needs to calculate a route. ready false means the items with severity blocker (for example no checking account, or no income) must be fixed in the NavFi app before a reroute; warnings do not stop one. Each item names the entity and the app screen that fixes it.

No arguments.

can_i_affordRead

Whether a purchase fits that week of the route, and what would have to give. outcome is fits_no_reroute (fits as is, or by moving money within the week), fits_reroute (fits, but only after a reroute) or insufficient_room (does not fit). destination.remaining_after is what is left after the purchase; changes lists money moved between categories before it, and its first row is the category itself. A preview: it changes nothing.

add_transactionWrite

Record a transaction on a manual account or card (manual: true in list_accounts; bank-linked ones post their own). amount is positive; the category's kind decides whether it is spending, income or a transfer. date can be up to 30 days back. Give account_id or credit_card_id, not both.

save_billWrite

Add a recurring bill, or edit one by passing its id from list_bills. due_date is the next date it is due. priority says what the route may postpone first in a shortfall: essential, important or optional. A bill paid by credit card has no paid-from account. Saving a bill suspends the route until a reroute; the result says so.

save_incomeWrite

Add an income source, or edit one by passing its id from list_income. amount is per paycheck; next_pay_date is the next one. Income lands in a checking account. Saving income suspends the route until a reroute; the result says so.

save_destinationWrite

Add a destination (a savings goal: an amount in a savings account by a date), or edit one by passing its id from get_goal_progress. A savings account holds one active destination. Saving a destination suspends the route until a reroute; the result says so.

plan_purchaseWrite

Put a one-off purchase on the route: an amount in a category on a date. Call can_i_afford first. If its outcome was fits_no_reroute, pass make_room true and its proposal_hash, and the route is adjusted at once. Otherwise the route is suspended and needs a reroute, which the result says. Nothing is paid; the route only plans for it.

mark_turn_doneWrite

Mark a turn on the route as done: a bill paid, a paycheck received, a planned purchase made. event_id comes from get_upcoming_events or plan_purchase. transaction_id (from get_transactions) links the real transaction; omit it to settle the turn without one. A settled turn is not planned again by the next reroute.

recategorize_transactionWrite

Change a transaction's category. transaction_id comes from get_transactions, primary_category_id from list_categories. Money that left an account cannot become income. If the new category changes what the transaction is (spending to a bill payment, say), its link to a turn is dropped; match_kept says whether it survived. NavFi learns the correction for similar transactions.

rerouteWrite

Recalculate the route from today's data. Use it after save_bill, save_income or save_destination, or when get_route_health advises one. It returns at once; the new route takes minutes, so poll get_route_status until generation_status is completed. If the user's data is not ready, the error lists what must be fixed in the NavFi app first (see get_readiness). Each reroute is a full recalculation, so there is a daily limit.