# yardstick-mcp

Talk to your [Yardstick](https://app.yardstick.money) money in plain language. This is an [MCP](https://modelcontextprotocol.io) server that lets an AI assistant like Claude read your Yardstick data, so instead of tapping through the app you can just ask: *"how much did I spend on eating out last month?"*, *"what's my net worth?"*, *"which subscriptions am I still paying for?"*

It runs on your own machine and, out of the box, it can only read: your data goes to your assistant and nowhere else, and nothing can be changed. If you want it to add things for you as well, there's an [opt-in switch](#letting-it-add-things) for that. More on all of this in [How your data is handled](#how-your-data-is-handled) below, because with a tool that can see your finances you should expect a straight answer before you install anything.

## What you can ask

Once it's connected, your assistant can answer things like:

- "What's my net worth, and how has it changed over the last year?"
- "Break down my spending by category for the last three months."
- "How much do I spend at Tesco in a typical month? Is that a lot compared to similar people?"
- "List my accounts and their balances."
- "Find every transaction over £200 since June."
- "How many months of outgoings could I cover from my current balances?"

It can read your accounts, transactions, holdings (assets and liabilities), net worth and your monthly financial vitals. It can never move money or make a payment. By default it can't change anything at all, so there's nothing it can do that you'd need to undo.

## Before you start

You'll need:

- **Node.js 20 or newer.** Check with `node --version`; if you haven't got it, [nodejs.org](https://nodejs.org) has installers.
- **A Yardstick account.**

## Install

### 1. Sign in

```bash
npx -y yardstick-mcp login
```

Your browser opens on Yardstick's normal sign-in page. Approve it, and you'll see a "you can close this tab" message. That's it, you're signed in. Your session is saved under `~/.config/yardstick-mcp/` (readable only by you) and refreshes itself from then on, so this is a one-time step. To sign out again, run `yardstick-mcp logout`.

### 2. Connect your assistant

Pick the one you use.

**Claude Desktop.** Open your config file (Settings → Developer → Edit Config, or `~/Library/Application Support/Claude/claude_desktop_config.json` on a Mac) and add:

```json
{
  "mcpServers": {
    "yardstick": {
      "command": "npx",
      "args": ["-y", "yardstick-mcp"]
    }
  }
}
```

Restart Claude Desktop. You'll see the Yardstick tools appear, and you can start asking questions.

**Claude Code.** One command:

```bash
claude mcp add yardstick -- npx -y yardstick-mcp
```

**Any other MCP client.** Anything that speaks MCP over stdio works the same way: run `yardstick-mcp` as the command with no arguments. Check your client's docs for where its server config lives.

> **Not on npm yet?** Until the package is published, run it from a checkout instead: clone the repo, `pnpm install && pnpm build`, then use `node /path/to/yardstick-mcp/dist/cli.js` wherever the instructions above say `npx -y yardstick-mcp`.

### 3. Ask something

Try *"what's my net worth?"* to check it's working. If the assistant says it isn't signed in, run the `login` step again; sessions last until you log out or revoke them, but this is the first thing to retry.

## Environments

By default the tool talks to production, your real Yardstick account, and if that's you, you can skip this section. For the Yardstick team and testers it can point at `staging`, `uat` or `local` (a dev stack on `localhost:8080`) instead: add `--env <name>` to the command, or set `env=<name>` in the server's environment (handy where env vars are easier to pass than arguments, e.g. `claude mcp add yardstick -e env=local -- npx -y yardstick-mcp`). The shorthands `prod`, `stage`, `dev` and `development` also work.

Each environment is its own world with its own sign-in and its own stored session. Sessions are kept side by side, so you can be signed in to several at once and configure them as separate servers:

```json
{
  "mcpServers": {
    "yardstick": {
      "command": "npx",
      "args": ["-y", "yardstick-mcp"]
    },
    "yardstick-uat": {
      "command": "npx",
      "args": ["-y", "yardstick-mcp", "--env", "uat"]
    }
  }
}
```

Or in Claude Code:

```bash
claude mcp add yardstick-uat -- npx -y yardstick-mcp --env uat
```

Sign in to the matching environment first:

```bash
npx -y yardstick-mcp login --env uat
```

Sign-in works out of the box on all four; each environment's client id is built in (uat and local share one, since they share a sign-in instance).

When it's connected to anything other than production, the server tells the assistant it's looking at test data, so staging numbers don't get presented as your real finances.

## The tools

Your assistant picks these automatically; you don't need to name them. For reference:

| Tool | What it gives you |
| --- | --- |
| `get_net_worth` | Assets, liabilities and net worth, broken down by group, class, liquidity and how liabilities are secured |
| `get_net_worth_history` | Month-end asset totals over time, for charting the trend |
| `list_accounts` | Your connected accounts with their latest balances |
| `list_holdings` | Everything on your balance sheet: property, pensions, investments, savings, mortgages, loans |
| `get_holding` | One holding in full, with its valuation history and (for a liability) its terms and payments |
| `search_transactions` | Your transactions, filtered by date, amount, merchant, category or free text |
| `aggregate_transactions` | Totals grouped by merchant, category, type or period, worked out on the server |
| `get_categorisation_stats` | How much of your history is categorised (so you know how complete an answer will be) |
| `get_top_merchants` | Where you spend most, by number of visits and total spend |
| `get_merchant_summary` | Your spending at one merchant, with an anonymous benchmark of what similar people spend |
| `get_spending_breakdown` | Income and spending by category, month by month |
| `get_vitals` | Monthly surplus, steady outgoings, wealth added and how many months your savings would cover |
| `list_categories` | Search the category list to find the right ones to filter by |

A couple of conventions, in case you're reading the raw output: money comes back both as an exact whole-number amount in minor units (pence) and as a ready-formatted string like `£1,234.56`, and spending amounts are always positive with the direction shown separately, so "money out" doesn't come through as a negative number.

## Letting it add things

There's an optional set of tools for putting things *into* Yardstick: adding a holding (a property, a pension, a loan) and recording what it's worth. Handy for *"add my flat, worth about £250k, I own half of it"* rather than filling in a form.

They're off unless you ask for them, because most people install this to ask questions and shouldn't have an assistant able to edit their records by accident. Turn them on with `--allow-writes`:

```bash
claude mcp add yardstick -- npx -y yardstick-mcp --allow-writes
```

or `YARDSTICK_ALLOW_WRITES=true` in the server's environment. That adds four tools: `list_economic_units` and `get_asset_taxonomy` (both read-only, they work out where a holding belongs and which classifications are valid), plus `create_holding` and `add_valuation`.

Worth knowing before you switch it on. There's no undo through this tool, so removing something means going into the app. There's also no duplicate protection: creating the same holding twice gives you two of them, so if you're not sure whether something worked, ask the assistant to list your holdings rather than try again. Your assistant should confirm the details with you before each write, and the tools are marked so your client can prompt you for approval; keep those prompts switched on. Still nothing here can move money or make a payment: the strongest thing it can do is add a record to your balance sheet.

## How your data is handled

Fair question to ask of anything that can see your bank data. The short version:

- **It runs on your machine.** There's no yardstick-mcp server in the middle. The tool talks straight to the Yardstick API, as you, and hands the results to your assistant.
- **It's read-only by default.** Nothing can be changed unless you [opt in to writes](#letting-it-add-things), and even then the most it can do is add a holding or record a valuation. It can never spend or move money, and it has no way to delete anything.
- **You only ever see your own data.** The tool signs in as you and sends no account identifier of its own; the Yardstick API decides what you can see from your sign-in alone, exactly as the app does. You can't point it at someone else's account, and it can't accidentally return one either. (This was checked with an independent security review before release.)
- **No telemetry.** The tool phones nothing home. It makes no network calls except to Yardstick and to Yardstick's sign-in provider.
- **Your session stays local.** Sign-in tokens are stored under `~/.config/yardstick-mcp/`, in files only your user account can read.

The one judgement that's yours: your assistant sees whatever data it fetches. Connect an assistant you're happy having read your finances, the same way you'd think twice before pasting a bank statement into any app.

## Configuration

Most people never need to set any of these; they're here for other environments and advanced setups.

| Variable | What it does | Default |
| --- | --- | --- |
| `YARDSTICK_OAUTH_CLIENT_ID` | OAuth client id for sign-in | built in per environment |
| `YARDSTICK_ALLOW_WRITES` | Expose the tools that add holdings and valuations; same as `--allow-writes` | `false` |
| `YARDSTICK_ENV` | Which Yardstick to use: `production`, `staging`, `uat` or `local` (or `prod`/`stage`/`dev`/`development`); same as `--env`, and plain `env` works too | `production` |
| `YARDSTICK_API_URL` | Point at a specific API base URL | set by `YARDSTICK_ENV` |
| `YARDSTICK_CLERK_DOMAIN` | Point sign-in at a specific domain | set by `YARDSTICK_ENV` |
| `YARDSTICK_API_VERSION` | The API version the tool targets | `2026-07-21` |
| `YARDSTICK_OAUTH_CLIENT_SECRET` | Only if your OAuth client is a confidential one | none |
| `YARDSTICK_OAUTH_SCOPES` | OAuth scopes to request | `openid profile email offline_access` |
| `YARDSTICK_OAUTH_REDIRECT_PORT` | Local port the sign-in redirect comes back on | `33418` |
| `YARDSTICK_TOKEN` | Use this bearer token as-is and skip sign-in | none |
| `YARDSTICK_TOKEN_COMMAND` | A command that prints a bearer token, run when one's needed | none |
| `YARDSTICK_TOKEN_SOURCE` | Which OAuth token to send: `id_token` or `access_token` | `id_token` |
| `YARDSTICK_CONFIG_DIR` | Where the session is stored | `~/.config/yardstick-mcp` |
| `YARDSTICK_PUBLIC_URL` | HTTP mode only: this server's public URL | request Host |

## Troubleshooting

**"Not signed in to Yardstick."** Run the `login` step. If you've moved machines or logged out, you'll need to sign in again there.

**The browser didn't open during sign-in.** The command also prints the sign-in URL; paste it into a browser yourself.

**"Could not listen on 127.0.0.1:33418."** Something's using that port. Set `YARDSTICK_OAUTH_REDIRECT_PORT` to a free one, but note the port has to be registered on the OAuth client, so if you're not the one who set that up, ask whoever did.

**The assistant can't see the tools.** Make sure you restarted it after editing the config, and that `node --version` is 20 or higher. In Claude Desktop, Settings → Developer shows whether the server started and any error it hit.

**A tool says the session expired.** Sign in again with `yardstick-mcp login`. Sessions refresh on their own, so if this keeps happening, your session may have been revoked on Yardstick's side.

## Running a shared server (experimental)

There's also an HTTP mode, for building a hosted connector rather than running per-person on a laptop:

```bash
yardstick-mcp serve --http --port 3555
```

It serves MCP over [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) at `/mcp`, and every request has to carry its own bearer token, which is passed straight through to the Yardstick API; the process keeps no credentials of its own. It's experimental: run it behind TLS, and set `YARDSTICK_PUBLIC_URL` to its real address. [docs/AUTH.md](docs/AUTH.md) has the detail.

## Development

```bash
pnpm install
pnpm build
pnpm test
```

The tests run the whole server against a fake Yardstick API, so they need no account and no network. [docs/AUTH.md](docs/AUTH.md) covers how sign-in works and how to set up an OAuth client for testing against staging.

## Licence

[MIT](LICENSE)