Skip to main content
Glama
cashcast-mcp

cashcast-mcp

README.md
# 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](https://github.com/nihadatakishiyev/cashcast-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nihadatakishiyev/cashcast-mcp/actions/workflows/ci.yml)

## Contents

- [Quick start](#quick-start)
- [Use it with your own data](#use-it-with-your-own-data)
- [Connect it to Claude](#connect-it-to-claude)
- [Example conversation](#example-conversation)
- [Tools and prompts](#tools-and-prompts)
- [Architecture](#architecture)
- [Design decisions](#design-decisions)
- [Security model](#security-model)
- [Development](#development)
- [Limitations](#limitations)

## Quick start

Requires Node.js 20 or later.

```bash
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:

```bash
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:

```bash
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

```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**

```bash
claude mcp add cashcast -- node /path/to/cashcast-mcp/dist/src/stdio.js --data /path/to/my-data
```

**Claude Desktop** (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "cashcast": {
      "command": "node",
      "args": ["/path/to/cashcast-mcp/dist/src/stdio.js", "--data", "/path/to/my-data"]
    }
  }
}
```

**Over HTTP**

```bash
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

```mermaid
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

```bash
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](LICENSE)

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