# SimpleFIN MCP Server

A small, self-contained MCP server that exposes [SimpleFIN](https://www.simplefin.org/protocol.html)
bank data (accounts + transactions) as tools for Claude Code.

It is independent of the shared Pipedream proxy — it just adds a second MCP
server to this workspace's `.mcp.json`.

## How SimpleFIN works

1. You generate a **setup token** (Base64) at a bridge, e.g.
   `https://bridge.simplefin.org/simplefin/create`.
2. The token decodes to a one-time **claim URL**. POSTing to it returns a
   permanent **Access URL** that embeds HTTP Basic credentials.
3. All data comes from `GET /accounts` on that Access URL.

A setup token can be claimed **only once**.

## Setup

```bash
cd C:\Users\Admin\John-Rommel\simplefin-mcp
npm install
```

### Connect (one time)

Get a setup token, then either:

```bash
npm run claim -- <YOUR_SETUP_TOKEN>
```

or run `node claim.js` and paste it when prompted. This saves the Access URL to
`credentials.json` (mode 600, gitignored).

To test without a real bank, skip the claim step and point the server at the
public demo Access URL via env (`SIMPLEFIN_ACCESS_URL`, see `.mcp.json` below):

```
https://demo:demo@beta-bridge.simplefin.org/simplefin
```

This demo returns three sample accounts (Savings, Checking, Empty) with real
transaction data, so you can exercise `list_accounts` and `get_transactions`
immediately.

## Register with Claude Code

Add this server alongside `pipedream` in `C:\Users\Admin\John-Rommel\.mcp.json`:

```json
"simplefin": {
  "command": "node",
  "args": ["C:/Users/Admin/John-Rommel/simplefin-mcp/index.js"]
}
```

If you'd rather pass credentials by env instead of `credentials.json`:

```json
"simplefin": {
  "command": "node",
  "args": ["C:/Users/Admin/John-Rommel/simplefin-mcp/index.js"],
  "env": { "SIMPLEFIN_ACCESS_URL": "https://user:pass@bridge.simplefin.org/simplefin" }
}
```

Restart Claude Code in this folder and approve the server once.

## Tools

| Tool | Purpose |
|------|---------|
| `claim_setup_token` | Exchange a setup token for an Access URL and save it. |
| `connection_status` | Report whether a connection is configured (no secrets shown). |
| `list_accounts` | List accounts + balances (fast, balances-only). |
| `get_transactions` | Fetch transactions, with optional date range / pending / account filter. |

## Security notes

- The Access URL is as sensitive as a banking password — `credentials.json` is
  written mode 600 and gitignored.
- All requests are HTTPS with verified certificates (Node default).