Skip to main content
Glama
cashcast-mcp

cashcast-mcp

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.

CI

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 data

npm 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.js

Use 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-data

The 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

version

yes

Always 1.

accounts[]

yes

id, name, type (cash or investment), balance (current), optional institution. Cash funds liquid goals; investment accounts fund investment goals.

categories[]

no

name and cardinality: must (rent, insurance), need (groceries, transport) or want (could stop tomorrow). Categories not listed are reported as unclassified.

goals[]

no

name, target, pool (liquid or investment), optional targetDate (YYYY-MM), annualReturnPct (investment goals, default 5) and milestoneOf (the goal whose pool this one marks a stretch of). Liquid goals fill in the order listed.

planned[]

no

Bills and expected income that are not in your history yet: description, amount, date, confidence (certain or tentative, default certain), optional repeat (monthly or yearly) and until.

savingsGoalPct

no

Share of regular income set aside each month. Default 0.

paceWindowMonths

no

Complete months the trailing averages use. Default 6.

contextNotes[]

no

Standing facts in your own words ("the bonus in March was one-off"). The model is told to treat them as authoritative.

smoothing[]

no

category and windowMonths: spreads a lumpy category over a trailing window for get_smoothed_spending.

transactions[]

no

Same fields as the CSV below, if you prefer JSON.

asOf

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

date

yes

booking date, transaction date, value date, posted

amount

yes

amount (eur), amount eur, value

account

if the file is not named after an account

account id

category

no

counterparty

no

payee, merchant, recipient, name

note

no

description, memo, purpose, reference text

id

no

transaction id, reference

transfer_id

no

transfer id, transferid

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-data

Claude 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/mcp

The 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

PORT

3030

Listening port.

PUBLIC_URL

http://localhost:PORT

Public origin. It becomes the OAuth issuer; clients connect to PUBLIC_URL/mcp.

LOGIN_PASSPHRASE

unset

Required on the consent page. Unset means one-click approval, labelled as local mode: fine on localhost, not on a public host.

TRUST_PROXY_HOPS

0

Reverse proxies in front of the server, so rate limiting sees real client addresses.

FINANCE_DATA

demo data

Data folder, if --data is not given.

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

get_overview

"Am I OK right now?" Net worth, what is left to spend this month, goals, the year so far.

get_spending

"Why was last month expensive?" One month by category and must/need/want, against a normal month and last year.

get_plan

"Where is this heading?" Goals with pace and landing months, pools, a 12-month forecast.

get_accounts

Balances per account and the year to date through the last complete month.

run_scenario

"Can I afford X?" and "What if X?" Net worth, savings rate and every goal, before and after.

what_would_it_take

"What would it take to reach X by Y?" One monthly gap, and what closing it does.

get_spend_history

Median, min, max and latest per category: where a cut could realistically come from.

get_records

Individual transactions for drill-down, with no totals.

get_forecast

Net worth projection over any horizon up to 60 months.

get_smoothed_spending

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 -.-> other

Path

Role

src/ledger.ts, src/csv.ts

The data format: zod schema, cross-field checks, CSV import.

src/data/

FinanceDataSource (one method, load()), FileDataSource, InMemoryDataSource.

src/engine/

All computation. engine.ts builds one view per tool; goals.ts, scenario.ts and what-would-it-take.ts hold the math.

src/summaries.ts

Trims full views to headline fields, by selection only.

src/tools.ts, src/prompts.ts, src/instructions.ts

The MCP surface.

src/auth/

OAuth provider, token store, consent page.

src/stdio.ts, src/http.ts, src/http-app.ts

Transports.

scripts/

The seeded generator behind examples/demo-data.

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 with X-Frame-Options: DENY and a strict Content Security Policy against clickjacking, with all dynamic text HTML-escaped. Deny returns access_denied to the client.

  • Protected resource metadata (RFC 9728) at the path-suffixed URL, with a WWW-Authenticate pointer 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.ts

The 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

MIT

Available Tools

10 tools
get_accountsAccountsA
Read-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 forecastA
Read-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_overviewOverviewA
Read-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_planPlanA
Read-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_recordsTransactionsA
Read-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 spendingA
Read-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 categoryA
Read-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 monthA
Read-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 scenarioA
Read-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 takeA
Read-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

    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

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that connects Claude to your Google Sheets for personal finance tracking, analysis, and reporting — all through natural language.
      2
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      A local-first MCP server that connects SimpleFIN bank accounts to Claude, storing data in a local DuckDB file and providing a web dashboard.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Self-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.
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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