cashcast-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cashcast-mcp If I buy a €2,000 laptop, when can I still hit my emergency fund goal?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cashcast-mcp
A personal-finance MCP server you run on your own data. Point it at a folder with your accounts, goals and a bank export, connect Claude, and ask the questions a budgeting app does not answer well: where you will be in a year, what a purchase does to your goals, what it would take to hit a target by a date. The server computes every figure itself and hands the model finished numbers to restate, so the answers are consistent and checkable. It runs locally over stdio, or remotely over Streamable HTTP behind a full OAuth 2.1 authorization server.
It was extracted from a private personal-finance app and ships with a fictional household as demo data, so it works the moment it is installed.
Contents
Related MCP server: goetta-finance
Quick start
Requires Node.js 20 or later.
git clone https://github.com/nihadatakishiyev/cashcast-mcp.git
cd cashcast-mcp
npm install # also builds dist/
npm start # stdio server on the bundled demo datanpm start speaks MCP on stdin and stdout, so on its own it just waits for a client. Connect it to Claude as shown below, or open it in the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/src/stdio.jsUse it with your own data
A data folder holds one finance.json and any number of .csv transaction files:
my-data/
finance.json accounts, goals, planned items, settings (required)
current.csv transactions, e.g. a bank export (optional, any number)Start from the demo and edit it:
cp -r examples/demo-data ~/my-data
node dist/src/stdio.js --data ~/my-dataThe folder is chosen by --data <path>, then the FINANCE_DATA environment variable, then the bundled demo. The server only ever reads it, and it re-reads it on every question, so edits apply without a restart.
A minimal finance.json
{
"version": 1,
"savingsGoalPct": 15,
"accounts": [
{ "id": "current", "name": "Current account", "type": "cash", "balance": 2400 },
{ "id": "etf", "name": "Index fund", "type": "investment", "balance": 18000 }
],
"categories": [
{ "name": "Rent", "cardinality": "must" },
{ "name": "Groceries", "cardinality": "need" },
{ "name": "Eating out", "cardinality": "want" }
],
"goals": [
{ "name": "Emergency fund", "target": 9000, "pool": "liquid" },
{ "name": "Retirement", "target": 450000, "pool": "investment", "annualReturnPct": 5 }
],
"planned": [
{ "description": "Car insurance", "amount": -480, "date": "2027-02-01", "repeat": "yearly" }
]
}finance.json reference
All amounts are in euros. Negative is money out, positive is money in.
Field | Required | Meaning |
| yes | Always |
| yes |
|
| no |
|
| no |
|
| no | Bills and expected income that are not in your history yet: |
| no | Share of regular income set aside each month. Default 0. |
| no | Complete months the trailing averages use. Default 6. |
| no | Standing facts in your own words ("the bonus in March was one-off"). The model is told to treat them as authoritative. |
| no |
|
| no | Same fields as the CSV below, if you prefer JSON. |
| no | Pins "today" to a date, for a snapshot. Leave it out for live data. |
Unknown fields are rejected rather than ignored, so a typo cannot silently drop a setting.
Transactions as CSV
One header row, then one transaction per row. Columns are matched by name, case-insensitively, and the common bank-export spellings are understood:
Column | Required | Also accepted as |
| yes |
|
| yes |
|
| if the file is not named after an account |
|
| no | |
| no |
|
| no |
|
| no |
|
| no |
|
Commas or semicolons both work. Amounts may be written 1234.56, -1,234.56, 1.234,56 or -12,50; dates 2026-01-31 or 31.01.2026. A file without an account column takes its account from its name, so a single account's export saved as current.csv belongs to the account current.
A move between two of your own accounts is two rows (one leg on each account) sharing a transfer_id. Transfers are never counted as income or spending, which is what keeps a monthly transfer to savings from looking like an expense.
When the data is wrong
Every problem is reported at once, with the file, the field and the line:
Invalid finance data:
- finance.json accounts[1].type: Invalid enum value. Expected 'cash' | 'investment', received 'savings'
- current.csv line 14: amount "twelve" is not a number
- transaction current.csv#22: account "joint" is not listed in accounts (known: current, etf)The model receives the same message as a tool error, so it can tell you what to fix.
Connect it to Claude
Use absolute paths. Leave out --data to use the demo.
Claude Code
claude mcp add cashcast -- node /path/to/cashcast-mcp/dist/src/stdio.js --data /path/to/my-dataClaude Desktop (claude_desktop_config.json)
{
"mcpServers": {
"cashcast": {
"command": "node",
"args": ["/path/to/cashcast-mcp/dist/src/stdio.js", "--data", "/path/to/my-data"]
}
}
}Over HTTP
LOGIN_PASSPHRASE='choose-a-long-one' npm run start:http -- --data /path/to/my-data
claude mcp add --transport http cashcast http://localhost:3030/mcpThe client discovers the authorization server, registers itself and opens a consent page in your browser. Enter the passphrase and approve. To use it as a custom connector on claude.ai, deploy it behind HTTPS and set PUBLIC_URL to that origin.
Variable | Default | Purpose |
|
| Listening port. |
|
| Public origin. It becomes the OAuth issuer; clients connect to |
| unset | Required on the consent page. Unset means one-click approval, labelled as local mode: fine on localhost, not on a public host. |
|
| Reverse proxies in front of the server, so rate limiting sees real client addresses. |
| demo data | Data folder, if |
Example conversation
Run against the demo data, a fictional person on 15 November 2026. Tool calls are shown in brackets; every figure is quoted from a tool result.
You: Can I afford an €1,800 e-bike in December?
Claude: [run_scenario: once, -1800, 2026-12] Here is what it does, so you can decide.
Net worth: the projection for November 2027 goes from €79,290.16 to €77,490.16, exactly €1,800 lower. The lowest point is €54,659.53 in December, the month of the purchase and of the dental bill, and it rises from there.
Savings rate: a one-off does not change your ongoing rate, which stays at 47.3% over the last six complete months.
Goals: the flat deposit moves from May 2028 to June 2028, which still meets its June 2028 target. Your emergency fund is already full. Retirement and the "First 75k invested" milestone on the way to it are untouched, because they draw on your index fund rather than your cash.
One thing the projection rests on: a €1,500 freelance invoice in January is marked tentative, and your own note says it is not confirmed. It roughly cancels out a tentative €1,600 summer holiday, so without both the November 2027 figure would be €79,390.16 before the e-bike.
You: What would it take to have the flat deposit by December 2027 instead?
Claude: [what_would_it_take: Flat deposit, 2027-12] You would need to be €485.86 a month better off than now: the date needs €1,979.19 a month into savings and you are running €1,493.33. A spending cut and a raise count the same, but a raise only helps if it is not spent.
Cutting is arithmetically possible, since you spend €2,332.84 in a typical month, but your "want" categories alone add up to €258.17 a month at their median, so they cannot close it by themselves. [get_spend_history] The largest is eating out at €160.44 a month (between €113.89 and €203.83). Groceries at €358.96 and rent at €1,240 are the big fixed items. Which of these would you consider changing?
Tools and prompts
All tools are read-only (readOnlyHint: true) and every result carries a freshness stamp.
Tool | Answers |
| "Am I OK right now?" Net worth, what is left to spend this month, goals, the year so far. |
| "Why was last month expensive?" One month by category and must/need/want, against a normal month and last year. |
| "Where is this heading?" Goals with pace and landing months, pools, a 12-month forecast. |
| Balances per account and the year to date through the last complete month. |
| "Can I afford X?" and "What if X?" Net worth, savings rate and every goal, before and after. |
| "What would it take to reach X by Y?" One monthly gap, and what closing it does. |
| Median, min, max and latest per category: where a cut could realistically come from. |
| Individual transactions for drill-down, with no totals. |
| Net worth projection over any horizon up to 60 months. |
| Raw against smoothed cost for lumpy categories. |
Prompts package the multi-step questions: check_in, can_i_afford, where_is_this_heading, what_would_it_take and why_was_this_expensive. Each names the tools to call, in order, and the caveat to check.
Architecture
flowchart LR
client["MCP client<br/>Claude Desktop, Claude Code, claude.ai"]
stdio["stdio transport"]
http["Streamable HTTP<br/>stateless, one server per request"]
oauth["OAuth 2.1<br/>DCR, PKCE S256, consent page,<br/>rotating refresh tokens"]
store[("OAuthStore<br/>hashed tokens")]
tools["MCP server<br/>10 read-only tools, 5 prompts,<br/>summary projection"]
engine["Engine<br/>goals, forecast, scenarios,<br/>spending, what-would-it-take"]
source["FinanceDataSource"]
files["FileDataSource<br/>finance.json + CSV"]
other["Your backend<br/>implements load()"]
client --> stdio --> tools
client --> http --> oauth --> tools
oauth --- store
tools --> engine --> source
source --> files
source -.-> otherPath | Role |
| The data format: zod schema, cross-field checks, CSV import. |
|
|
| All computation. |
| Trims full views to headline fields, by selection only. |
| The MCP surface. |
| OAuth provider, token store, consent page. |
| Transports. |
| The seeded generator behind |
To plug in a database or a bank-sync service, implement FinanceDataSource.load() to return a ledger and pass it to createServer() (stdio) or createHttpApp() (HTTP). Nothing else changes.
Design decisions
Restate, never re-derive. The engine is the only place a figure is computed. Tool results name every figure the model might want (left to spend, savings rate, goal landing months, the forecast without tentative income) and the server instructions tell the model to quote them rather than rebuild them from parts. A model doing arithmetic on a payload produces confident numbers that differ from the app's, with no working shown. The original app removed several drifting copies of one savings-rate formula before adopting this rule.
Summary by default, selection only. The four view tools return a trimmed payload unless asked for detail: "full", which keeps per-day and per-month series out of the conversation until they are the answer. src/summaries.ts may only select fields, and test/summaries.test.ts enforces it: every summary value must be the same object reference as in the full payload, so a summary that recomputes or even rebuilds a value fails the build.
Consequences, not verdicts. run_scenario reports what a decision does to net worth, the savings rate and each goal, and leaves the decision to the person. Results are discriminated unions (one-off versus shifted, never versus a month, no_lever versus gap) so a reader cannot quote a number where there is none.
Pools decide which goals move. Cash goals fill in order like a waterfall; investment goals are fed by contributions and grow at their own rate. A cash scenario lists investment goals as untouched rather than dropping them, because "this does not affect your retirement" is part of the answer.
Read-only. No tool writes anything, and the file source only opens files for reading.
Errors the model can act on. A data problem returns as a tool error naming the file, field and line, so the conversation can fix it.
Security model
The HTTP mode is an OAuth 2.1 authorization server and resource server in one process, built on the MCP TypeScript SDK's auth router with this project's provider.
Dynamic client registration (RFC 7591). MCP clients register themselves; public clients get no secret.
PKCE with S256 only, verified on every code exchange.
Authorization codes live 60 seconds and are single use. Consumption is a conditional write, so two concurrent exchanges of one code cannot both succeed. A code is bound to its client and its
redirect_uri.Access tokens live 60 minutes. Refresh tokens live 30 days and rotate on every use; the old one dies in the same step that issues the new one. A refresh can narrow scope, never widen it.
Tokens are stored as SHA-256 hashes. The store never sees a raw token, so a leaked row or log line cannot be replayed. A test wraps the store in a spy and fails if any raw token reaches it.
Constant-time comparison for the passphrase and the redirect URI.
Consent page: an approval with a passphrase (
LOGIN_PASSPHRASE), rate limited, sent withX-Frame-Options: DENYand a strict Content Security Policy against clickjacking, with all dynamic text HTML-escaped. Deny returnsaccess_deniedto the client.Protected resource metadata (RFC 9728) at the path-suffixed URL, with a
WWW-Authenticatepointer on every 401.Revocation (RFC 7009) is supported and idempotent.
InMemoryOAuthStore keeps tokens for the life of one process. For serverless or several instances, implement OAuthStore over a database; schema/oauth.sql is a Postgres schema for it. The consent page is the one place to change for real identity: replace src/auth/login.ts with a magic-link or SSO flow and call completePendingAuthorization() once the user is verified. The original deployment used an email magic link restricted to a single pre-existing user.
Development
npm test # vitest
npm run typecheck # tsc --noEmit over src, test and scripts
npm run build # compile to dist/
npm run demo:generate # rewrite examples/demo-data from scripts/demo-ledger.tsThe tests cover the data format and CSV import, the engine's math, every tool through a real MCP client, the summary selection rule, the OAuth provider, and the full HTTP flow from discovery to an authenticated tool call. A test also checks that examples/demo-data parses to exactly what the generator produces and that every tool answers identically from either. CI runs typecheck and tests on Node 20, 22 and 24.
Limitations
One currency (EUR) and one person.
The forecast uses trailing averages with no seasonality, and models no investment growth (goals do apply their return rate).
A one-off scenario is applied to today's cash pool, which is exact from the scenario month on.
In-memory OAuth state is lost on restart; clients simply reconnect.
License
Available Tools
10 toolsget_accountsAccountsARead-onlyIdempotent
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.
Inputs: detail.
get_forecastNet worth forecastARead-onlyIdempotent
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.
Inputs: horizon_months.
get_overviewOverviewARead-onlyIdempotent
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.
Inputs: detail.
get_planPlanARead-onlyIdempotent
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.
Inputs: detail.
get_recordsTransactionsARead-onlyIdempotent
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.
Inputs: to, from, limit, account, +4 more.
get_smoothed_spendingSmoothed spendingARead-onlyIdempotent
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.
Inputs: months_back.
get_spend_historySpend history by categoryARead-onlyIdempotent
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.
Inputs: months.
get_spendingSpending for a monthARead-onlyIdempotent
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.
Inputs: month, detail.
run_scenarioRun a what-if scenarioARead-onlyIdempotent
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.
Inputs: kind (required), month (required), amount_eur (required).
what_would_it_takeWhat would it takeARead-onlyIdempotent
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.
Inputs: goal (required), by_month (required), assume_spend_cut_eur, assume_extra_income_eur.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
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'.
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.
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.
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
Related MCP Connectors
Ask Claude about your income and spending, and import bank statements. No bank login.
Personal finance, bank account, and shared memory connector for Claude, ChatGPT, Gemini Spark & more
Read-only access to your own bank, card and brokerage accounts for Claude, ChatGPT and other AI agents: balances, transactions, spending, subscriptions, cashflow and investment holdings. It can never move money.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that connects Claude to your Google Sheets for personal finance tracking, analysis, and reporting — all through natural language.2-
- AlicenseNot gradedqualityBmaintenanceA local-first MCP server that connects SimpleFIN bank accounts to Claude, storing data in a local DuckDB file and providing a web dashboard.2MIT
- AlicenseNot gradedqualityBmaintenanceSelf-hostable remote MCP server for Lunch Money with built-in OAuth 2.1, enabling Claude to access transactions, budgets, and more on mobile, web, and desktop.1MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that connects Claude (and other MCP clients) to your Monarch Money financial data, allowing you to query accounts, transactions, and budgets, or update transactions and budget amounts through natural language.MIT