yardstick-mcp

Talk to your Yardstick money in plain language. This is an MCP 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 for that. More on all of this in 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 has installers.
• A Yardstick account.

Install

1. Sign in

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:

{
  "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:

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:

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

Or in Claude Code:

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

Sign in to the matching environment first:

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:

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, 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:

yardstick-mcp serve --http --port 3555

It serves MCP over 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 has the detail.

Development

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 covers how sign-in works and how to set up an OAuth client for testing against staging.

Licence

MIT