# up-bank-mcp

A Cloudflare Workers-based MCP server for the [Up Banking API](https://developer.up.com.au/). It can read your accounts and transactions, summarises spending, and can categorise and tag transactions.

Up's terms don't currently allow you to provide your personal access token to anyone else, so you will need to deploy your own instance of this system to your own Cloudflare.

## Tools

**Reads:** `ping`, `list_accounts`, `get_account`, `get_balances`,
`list_categories`, `list_tags`, `get_transaction`, `list_transactions`

**Analysis:** `search_transactions`, `summarize_spending`, `cash_flow`,
`find_recurring`

**Writes:** `categorize_transaction`, `add_transaction_tags`,
`remove_transaction_tags`

## Setting It Up

Running this requires a Cloudflare account with **Workers Paid**: the free plan caps at 50 external subrequests and 10ms of CPU per invocation, and a year-long summary is dozens of Up requests and will involve processing before returning to your agent.

### 1. Create the KV namespace

```bash
npx wrangler kv namespace create OAUTH_KV
```

Paste the returned id over the placeholder in `wrangler.jsonc`.

### 2. Set the vars

Both live in `wrangler.jsonc`. `PUBLIC_URL` has to match the deployed Worker URL
exactly, because it's what gets handed to the OAuth provider in preference to
anything derived from the inbound `Host` header.

`DEFAULT_TIMEZONE` is the one line most people will need to change:
`Australia/Brisbane`, `/Sydney`, `/Melbourne`, `/Hobart`, `/Adelaide`, `/Darwin`
or `/Perth`. It decides where a month starts, so a wrong value here doesn't throw
an error, it just quietly shifts your totals.

### 3. Set the secrets

```bash
npx wrangler secret put UP_API_TOKEN
```

```bash
npx wrangler secret put OWNER_PASSPHRASE
```

The Up token comes from <https://api.up.com.au/getting_started>. Generate the
passphrase rather than picking one, for reasons in the design notes below:

```bash
openssl rand -base64 32
```

### 4. Deploy

```bash
npm run cf-typegen && npm run deploy
```

Add `https://<your-host>/mcp` to any MCP client. It'll ask for the passphrase the
first time you connect.

### 5. Check It Works

```bash
BASE=https://<your-host> PASSPHRASE='...' npm run smoke
```

This walks the whole handshake, lists the tools, then runs real read-only queries
against your account: balances, a 90-day category summary, cash flow and
recurring detection. It calls no write tool and changes nothing. Worth running
after the first deploy, and after any change to the auth path.

## Local Development

```bash
cp .dev.vars.example .dev.vars
```

Fill it in, then:

```bash
npm run dev
```

```bash
npm run check
```

`check` runs the linter, the type-checker and 46 tests. The tests execute in
workerd through `@cloudflare/vitest-pool-workers`, which matters more than it
sounds like it does: the timezone logic depends on ICU, and that's the same ICU
build production runs.

`npm run smoke` works against local dev too. If `.dev.vars` still has the
placeholder token it reports Up's 401 as a pass and skips the Up-facing checks,
so it's useful before you have a token as well as after.