Skip to main content
Glama
cashcast-mcp

cashcast-mcp

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
PORTNoListening port for HTTP mode. Default: 3030.
PUBLIC_URLNoPublic origin for HTTP mode. It becomes the OAuth issuer; clients connect to PUBLIC_URL/mcp. Default: http://localhost:PORT.
FINANCE_DATANoPath to the data folder containing finance.json and optional CSV transaction files. Used if --data is not given. Defaults to the bundled demo data.
LOGIN_PASSPHRASENoPassphrase required on the consent page in HTTP mode. Unset means one-click approval, labelled as local mode.
TRUST_PROXY_HOPSNoNumber of reverse proxies in front of the server, so rate limiting sees real client addresses. Default: 0.

Instructions

Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.

Cashcast is a personal finance server for one person. Its purpose is decision support and forecasting, not reporting.

RESTATE, NEVER RE-DERIVE. Every figure these tools return is already the authoritative computation. Do not recompute a savings rate, a goal date, a left-to-spend figure or a net worth from component parts, even when the parts are in the payload and the arithmetic looks trivial. If a figure you want is not returned, say it is not available rather than deriving it.

TRANSFERS ARE NEVER INCOME OR EXPENSE. A transaction moving money between two of the user's own accounts is a transfer, identified by a non-null transferId, and is excluded from all income and spending analysis. get_records excludes transfers by default and labels them when include_transfers is set; never fold one into a total.

"LEFT TO SPEND" is what remains this month: regular monthly income minus (savings goal + spend so far + planned bills still to come this month).

NEVER RENDER A VERDICT. There are no pass/fail thresholds. Do not answer "yes, you can afford it" or "that is unaffordable". Answer with consequences: what it does to the projected net worth, to the ongoing savings rate, and to each goal's landing month. run_scenario returns exactly those three things.

READ contextNotes FIRST. get_overview and get_plan lead with the user's own standing facts (what is temporary, what was decided). They are authoritative: cite them and check them before calling anything permanent, temporary or missing.

WHICH POOL THE MONEY LEAVES decides which goals move. Liquid goals draw on cash accounts and fill in the order listed; investment goals draw on investment accounts and are untouched by a change to spending. "This does not affect your retirement goal" is a fact the user needs, so never drop goals whose outcome is "none".

A MILESTONE IS NOT A RIVAL GOAL. A goal with isMilestone true marks a stretch of its parent's pool (milestoneOf). Never add a milestone's figures to its parent's, and say which goals are milestones rather than listing them as peers.

THE FORECAST PROJECTS NET WORTH, NOT SPENDABLE CASH. Moving cash into an investment account leaves net worth unchanged. Investment growth is not modelled, so the forecast is a contributions-only view. The baseline income and spend are flat trailing averages with no seasonality; a trip or annual bill appears only if it was entered as a planned item.

PLANNED ITEMS COUNT AT FACE VALUE, whatever their confidence. When "tentative" items materially hold up a projection, name them and quote endNetWorthWithoutTentativeEur.

YEAR TO DATE MEANS TWO WINDOWS, and both are correct. get_overview's yearSoFar runs to today, including the partial month; get_accounts' ytd figures stop at the last complete month. Check the stated windows before calling a difference a discrepancy, and name the window when you cite either.

STATE THE DATA'S AGE when recency matters. Every response carries a freshness stamp; a snapshot (snapshotAsOf) is a fixed date, not today.

EXTRA INCOME ONLY HELPS IF IT IS NOT SPENT. The savings pace behind every goal date is measured from history, so a euro not spent and a euro of extra income move it identically. State that assumption whenever you quote an income figure.

THE SERVER DOES NOT DECIDE WHAT IS REALISTIC TO CUT. get_spend_history reports each category's typical month and its spread; the judgement belongs in the conversation. When no amount of cutting reaches a gap, that is arithmetic.

TOOL CHOICE. get_overview, get_spending, get_plan and get_accounts default to a trimmed payload; pass detail "full" only when the series are the answer. run_scenario answers "what if" and "can I afford"; what_would_it_take is its inverse. get_records is for drill-down and returns rows with no totals.

Capabilities

Features and capabilities supported by this server

Protocol revision2025-11-25

CapabilityDetails
tools
{
  "listChanged": true
}
prompts
{
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
get_overviewA

Start here for 'am I OK right now'. Net worth with its cash and investment split, this month's spend, what is left to spend and the bills still to come, the trailing savings rate, every goal's progress and projected landing month, the year so far and what a normal month looks like. Leads with contextNotes, the user's standing facts. yearSoFar runs to today and includes the current partial month, unlike get_accounts' ytd figures.

get_spendingA

One month's spending by category and by must/need/want, against a normal month (the median of the preceding complete months) and the same month last year, plus that month's planned bills. Answers 'why was last month expensive'. Transfers are excluded.

get_planA

Where this is heading: every goal's target, progress, pace, required pace and projected landing month, the liquid and investment pools and the pace feeding each, the trailing income, spend and savings rate, a 12-month net worth forecast and the planned items behind it with their confidence. For 'what if', use run_scenario.

get_accountsA

Observed state: each account's balance and type, cash and investment totals, and the year to date income, spend, amount invested and savings rate. The ytd figures run to the LAST COMPLETE MONTH (ytdWindow states it), so they differ from get_overview's yearSoFar by the current month. That is two windows, not a discrepancy.

run_scenarioA

The tool for 'can I afford X' and 'what if X'. Applies one hypothetical change and reports three consequences: projected net worth with its delta and low point, the ongoing savings rate before and after, and every goal's landing month before and after with the pool it draws on. Consequences only, never a verdict. A one-off does not change the ongoing savings rate, and the result says so instead of giving a delta.

what_would_it_takeA

The inverse of run_scenario, for 'what would it take to hit X by Y'. Returns ONE number, the monthly gap between the pace the date needs and the pace being run, plus every goal's landing month once it is closed. A spending cut and extra regular income close it one to one: pass what the user can already find and read residualGapEur. Extra income only helps if it is not spent; say so. When the outcome is not a gap (no_lever, date_passed, on_track) report the reason, not a number.

get_spend_historyA

Where a cut could come from: for each category over the trailing complete months, the MEDIAN month with its min, max and latest, zero-filled so monthsPresent shows how lumpy it is. Median, not mean: one unusual month must not suggest headroom that is not there. The server does not decide what is realistic to cut; that judgement is the user's.

get_recordsA

Individual transactions, for drilling into a figure another tool reported. Returns ROWS AND NO TOTALS by design. Transfers between the user's own accounts are excluded unless include_transfers is set, and are labelled isTransfer when included.

get_forecastA

Projects NET WORTH month by month from next month: trailing average income and spend plus planned items (bills still due this month fold into the first row). Explain the numbers, do not recompute them. Investment growth is not modelled and transfers to investments leave net worth unchanged. Planned items count at face value whatever their confidence; endNetWorthWithoutTentativeEur is the end figure without tentative ones.

get_smoothed_spendingA

Raw against smoothed monthly cost for each configured smoothing rule, which spreads a lumpy category (travel, annual insurance) over a trailing window. Use it to tell whether an expensive month was genuinely unusual. Empty when no rules are configured.

Prompts

Interactive templates invoked by user choice

NameDescription
check_inThe 30-second check: anything off, am I overspending this month, is anything due.
can_i_affordConsequences of a purchase or a recurring change: net worth, savings rate and every goal's landing month.
where_is_this_headingGoal progress and trajectory under current habits, and what the projection rests on.
what_would_it_takeName a goal and a month; get the monthly change that lands it and where a cut could come from.
why_was_this_expensiveRetrospective on one month: what moved against a normal month and whether it was unusual.

Resources

Contextual data attached and managed by the client

NameDescription

No resources

TDQS

A4/5.0

Scored across 10 tools

Disambiguation4/5

Most tools have a clearly stated job and the descriptions actively pre-empt confusion (e.g. get_overview's yearSoFar vs get_accounts' ytd window, get_spending vs get_spend_history vs get_smoothed_spending). The weak spot is the projecting triad: get_plan, get_forecast and get_overview all surface goal landing months and net-worth projections, so an agent can reasonably hesitate over which to call for 'where am I heading'.

Naming Consistency4/5

Eight of ten tools follow a clean get_/verb_noun snake_case pattern (get_overview, get_records, get_forecast, run_scenario). The outliers are what_would_it_take (a question-phrase rather than verb_noun) and the mildly inconsistent get_spending vs get_spend_history word order, both still readable.

Tool Count5/5

Ten tools is squarely in the well-scoped range, and each one maps to a distinct question a personal-finance user actually asks (status, spending, plan, history, accounts, scenario, inverse scenario, records, forecast, smoothing). Nothing looks padded or redundant at the count level.

Completeness4/5

The analytical surface is thorough — read, drill-down, forecast, scenario and inverse-scenario all exist, with no obvious dead end for a question an agent would be asked. The gap is that the server is entirely read-only: there is no way to add or edit transactions, goals or accounts, so any workflow requiring mutation would fail.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues