# MyFinance MCP

A remote MCP server for personal finance - log expenses by talking, snap receipt photos, import whole bank statements, and get budgets, trends and net worth computed for you, in any currency.

**Website:** [myfinance-mcp.com](https://myfinance-mcp.com) · Free while in beta · Built by [Rteam](https://rteam.agency)

## Quick Start

Already hosted and ready to use - just connect it to your MCP client:

```
https://myfinance-mcp.com/mcp
```

**On Claude.ai:** Customize → Connectors → **+** → Add custom connector → paste the URL → Connect. Leave the OAuth Client ID and Client Secret fields **empty** - filling them breaks sign-in.

**On ChatGPT:** Settings → Apps → Create app → paste the URL → choose OAuth → Create.

On first connect you sign in with Google or register with an email and password. Your data persists across reconnections.

## Why

- **No app, no forms, no spreadsheet.** "Spent 24.50 eur on groceries at Lidl" is the whole workflow.
- **Every number is computed in SQL.** The server owns the data and the math; the AI reads the results, it never guesses arithmetic.
- **Any currency.** Transactions keep their original currency; the FX rate to your base currency is frozen at transaction date, so history never rewrites itself.
- **Statements in one message.** Drop a CSV/PDF export; hundreds of rows import in one call with idempotent deduplication, hand-logged twins merged, totals reconciled.
- **Personal vs business.** Entity tag on accounts and transactions, filterable everywhere, included in CSV export for your accountant.
- **Dashboards in the chat.** Budgets, trends, summaries and accounts render as interactive panels (MCP Apps) right in the conversation.

## Tech Stack

- **Bun** - runtime and package manager
- **Express** - HTTP layer
- **MCP SDK** - Model Context Protocol over Streamable HTTP (stateless)
- **OAuth 2.1** - PKCE + dynamic client registration, Google sign-in optional
- **Prisma + PostgreSQL** - all money as `numeric`, all stats as SQL aggregates
- **Docker** - single container deployment

## MCP Tools

| Tool                  | Description                                                                                        |
| --------------------- | -------------------------------------------------------------------------------------------------- |
| `log_expense`         | Record one purchase, bill or receipt (negative amount = refund)                                    |
| `log_income`          | Record income: salary, invoice, refund, interest                                                   |
| `log_transfer`        | Move money between accounts, cross-currency supported; never counts as spending                    |
| `log_balance`         | Anchor an account's balance at a date; later flows compute from the snapshot                       |
| `import_transactions` | Bulk statement import (up to 500 rows/call): dedup by bank reference or derived key, twin merge, reconciliation check |
| `create_account`      | Create a bank / card / cash / investment account with currency and personal/business entity        |
| `update_account`      | Rename an account or change its type, entity or main currency                                      |
| `delete_account`      | Delete one money account (with its transactions after explicit confirmation)                       |
| `merge_accounts`      | Fold one account into another: move rows, de-duplicate both sides, rewrite transfers               |
| `get_accounts`        | All accounts with balances and net worth, converted to base currency                               |
| `get_summary`         | Period totals by category, merchant or month; expense or income breakdown, category drill-down and exclusions |
| `get_transactions`    | List and filter raw transactions                                                                   |
| `get_trends`          | Month-over-month spending trends and deltas                                                        |
| `set_budget`          | Monthly cap per category or overall                                                                |
| `get_budget_progress` | Live budget progress with days left; renders as a dashboard                                        |
| `update_transaction`  | Fix any field of an existing transaction, including its type (e.g. turn a cash withdrawal into a transfer); category fixes are remembered per merchant for future syncs |
| `delete_transaction`  | Delete one transaction by id                                                                       |
| `delete_transactions` | Bulk delete by ids                                                                                 |
| `get_settings`        | Base currency and timezone                                                                         |
| `update_settings`     | Change base currency or timezone                                                                   |
| `export_transactions` | Full CSV export (includes the entity column for accountant handoff)                                |
| `connect_bank`        | Link a real bank via open banking (Enable Banking, EU/UK): list banks, start consent, status, per-account sync toggle, disconnect |
| `sync_bank`           | Pull booked transactions and balances from the connected bank; incremental, transfer pairing, dedup-safe. Healthy connections also auto-sync server-side roughly daily |
| `connect_zenmoney`    | Link a ZenMoney account (international and .ru backends auto-detected) for read-only sync          |
| `sync_zenmoney`       | Pull ZenMoney accounts and transactions; incremental, dedup-safe, keeps your manual edits          |
| `delete_all_data`     | Permanently delete the user profile and ALL data (GDPR erasure)                                    |
| `ping`                | Health and auth check                                                                              |

## MCP Apps

Four tools return an interactive dashboard (`ui://myfinancemcp/dashboard`) rendered directly in the chat on clients that support MCP Apps: budget rings, monthly trends, category summaries and the accounts/net-worth panel. Light and dark theme aware.

## Security & Privacy

- Receipt photos are parsed by YOUR AI client; images never reach this server.
- Amounts, merchants and notes are never written to server logs (blind logs); telemetry stores event types and ids only.
- OAuth 2.1 with PKCE, encrypted tokens, rate-limited sign-in.
- All 27 tools carry MCP annotations (read-only and destructive ops flagged, connector tools marked open-world), so clients can gate confirmations correctly.
- Bank access is strictly read-only: open banking consent via Enable Banking (the bank authenticates the user; we never see credentials), ZenMoney via the user's own API token. Session ids and tokens are stored AES-256-GCM encrypted.
- CSV export and instant full deletion are tools, not support tickets.
- Hosted instance: EU data residency, row-level security keyed to your account.
- 154 automated end-to-end checks (full OAuth flow, every tool, import dedup semantics, GDPR deletion) run in CI and as a hard deploy gate.

See [SECURITY.md](SECURITY.md) for the disclosure policy.

## Self-hosting

MIT-licensed; runs anywhere Bun and Postgres run.

### 1. Postgres

Any PostgreSQL 15+ works. [Supabase](https://supabase.com) free tier is a good fit: create a project and copy the **session pooler** connection string (IPv4).

Apply the schema:

```bash
bun install
bunx prisma db push
```

### 2. Environment variables

| Variable                      | Description                                                        |
| ----------------------------- | ------------------------------------------------------------------ |
| `PORT`                        | Server port (default `8788`)                                       |
| `BASE_URL`                    | Public URL of the server (OAuth issuer)                            |
| `DATABASE_URL`                | Postgres connection string                                         |
| `MYFINANCE_MCP_EMAIL`         | Bootstrap user email                                               |
| `MYFINANCE_MCP_PASSWORD_HASH` | Bootstrap user password hash (see below)                           |
| `GOOGLE_CLIENT_ID`            | _(optional)_ Google OAuth client ID for "Continue with Google"     |
| `GOOGLE_CLIENT_SECRET`        | _(optional)_ Google OAuth client secret                            |
| `RESEND_API_KEY`              | _(optional)_ Resend key for new-signup email notifications         |
| `NOTIFY_EMAIL`                | _(optional)_ Where signup notifications go                         |
| `FROM_EMAIL`                  | _(optional)_ Verified sender for notifications                     |
| `AUTO_SYNC_INTERVAL_MS`       | _(optional)_ Bank auto-sync tick, default hourly (syncs connections >20h stale); `0` disables |

Generate the password hash:

```bash
bun -e "console.log(await Bun.password.hash(process.argv[1]))" 'your-password'
```

### 3. Run

```bash
docker compose up -d      # uses the included Dockerfile, port 8788
```

Put nginx (or any TLS-terminating proxy) in front and point `BASE_URL` at your domain. The static landing in [`site/`](site/) is optional - serve it from the same origin if you want one.

## Development

```bash
bun install
cp .env.example .env   # fill in your values
bun run dev            # hot reload on :8788
bun run e2e            # self-contained end-to-end suite (spawns its own server)
bun run lint
```

The e2e suite (154 checks) covers the full OAuth flow (discovery, dynamic registration, PKCE, refresh rotation), every tool, statement-import dedup semantics, ZenMoney sync against a stubbed Diff API, and GDPR deletion.

## API Endpoints

| Endpoint                                       | Description                              |
| ---------------------------------------------- | ---------------------------------------- |
| `POST /mcp`                                    | MCP endpoint (Bearer auth)               |
| `GET /health`                                  | Health check                             |
| `GET /.well-known/oauth-authorization-server`  | OAuth metadata discovery                 |
| `GET /.well-known/oauth-protected-resource/mcp`| Protected resource metadata              |
| `POST /register`                               | Dynamic client registration              |
| `GET /authorize`                               | OAuth authorization (sign-in page)       |
| `POST /token`                                  | Token exchange                           |
| `GET /auth/google`                             | Google sign-in start (when configured)   |
| `GET /api/stats`                               | Public aggregate counters (counts only, never amounts) |

## License

[MIT](LICENSE) - Rteam FZE LLC