fineye-mcp — your FinEye finances, for AI agents

Unofficial & independent. This is a personal-use, community client for the FinEye app's API. It is not affiliated with, endorsed by, or supported by FinEye. It reaches only your own data with your own login. No warranty — use at your own risk. The embedded Supabase anon key is the app's public key (shipped in the FinEye client), not a secret.

An MCP server that gives an AI agent typed access to your FinEye personal finances — accounts, transactions, budgets, categories, tags, holdings and spend analytics — with writes behind explicit safety gates and deletes behind two more. The same code also ships a CLI and a terminal dashboard.

These are real financial records, not a sandbox. The design assumes that from the start: the default mode cannot delete anything, read-only mode does not even register the write tools, and every destructive call is a preview until you confirm it.

Quick start

npm install && npm run build
node dist/index.js login          # Google OAuth, token stored at ~/.config/fineye/session.json
npm link                          # optional: puts `fineye` on your PATH

Register it with Claude Code:

claude mcp add fineye -s user -- fineye mcp                          # read + write
claude mcp add fineye -s user -e FINEYE_DELETE=1 -- fineye mcp       # read + write + delete
claude mcp add fineye-ro -s user -e FINEYE_READONLY=1 -- fineye mcp  # read-only

Any other MCP client takes the same command:

{
  "mcpServers": {
    "fineye": {
      "command": "node",
      "args": ["/absolute/path/to/fineye-mcp/dist/index.js", "mcp"],
      "env": {},
    },
  },
}

The tools

20 tools. Ten of them only read.

Tool	What it does
fineye_workspaces	which account the server is logged in as, and the active workspace
fineye_accounts	balances; view='goals' for savings goals, view='holdings' for crypto/stocks
fineye_networth	net worth in the main currency, per-account breakdown, optional daily history
fineye_transactions	rows with a derived type (expense/income/transfer) and scheduled flag
fineye_analytics	income/expense/net + spend breakdown by category, sub-category, tag or merchant
fineye_budget	the period budget against actual spend; action='history' for past periods
fineye_categories · fineye_tags	the hierarchies, for turning a name into an id
fineye_notifications	the in-app inbox — where FinEye announces product changes
fineye_export	transactions as CSV or JSON, inline
fineye_playbook	task guidance (see below)
fineye_add · fineye_tx	create a transaction; edit / tag / split / refund / copy / set recurring
fineye_category · fineye_tag · fineye_account	create and edit; categories can be archived (reversible) instead of deleted
fineye_budget_set	set the total budget for a period
fineye_rules	auto-categorization rules — they apply to FUTURE transactions only
fineye_delete · fineye_bulk	permanent deletion; bulk recategorize / tag / delete

Anywhere a tool takes an account, category, tag or parent, a name or an id works. Parameters literally named id are always raw ids.

Modes and gates

The environment decides what the server can do at all:

env	effect
(none)	read + write. The delete tools are registered, but every delete is refused.
FINEYE_DELETE=1	deletes become possible — still only with confirm: true on each call.
FINEYE_READONLY=1	write and destructive tools are not registered at all; 12 read tools remain.

FINEYE_DELETE is set once, when the server is registered, and holds for the session — so it is a capability, not a confirmation. That is why every destructive call also needs confirm: true; without it the tool returns a preview of what would go and changes nothing. fineye_bulk is a dry run unless apply: true, and needs apply and confirm to delete.

Underneath the MCP layer the client enforces per-verb allow-lists (WRITABLE_TABLES, PATCHABLE_TABLES, DELETABLE_TABLES in src/client.ts); any other table or HTTP verb is rejected. Deletes accept a single id=eq.<id> filter — there is no mass-delete path — and bulk deletes write a JSON backup to /tmp first. Accounts and workspace settings can never be deleted. Scheduled installments are held back from bulk deletes unless you ask for them.

Errors carry a machine-readable code (auth, forbidden, not_found, gate, invalid, network, api), so an agent can tell "no such transaction" from "the network is down" without matching on message text. The CLI maps the same codes to exit statuses (3, 4, 5, 4, 2, 6, 1).

Concurrency: writes replace whole JSON fields rather than merging them, so avoid editing the same record in the phone app at the same moment — last writer wins.

Playbooks

Server instructions are sent on every connection, so they stay short. The deeper guidance — the traps that actually cost someone a wrong number — is loaded only when a task calls for it:

• monthly-review — the order of calls that produces a correct monthly picture
• safe-bulk-changes — dry-run, verify the matched count, then apply
• test-without-polluting — the create → act → delete canary, and what cannot be undone
• find-and-fix-categories — rules fix the future, bulk fixes the past

They are served both as MCP resources (fineye://playbooks/<id>) and through the fineye_playbook tool, because client support for resources is uneven. The data-model semantics are shared with the CLI agent skill (src/skill/semantics.ts) so the two cannot drift apart.

Remote access (HTTP)

For a client that cannot spawn a local process — a hosted chat UI, say — the server also speaks Streamable HTTP:

export FINEYE_MCP_TOKEN=$(openssl rand -hex 24)
fineye mcp --http --port 8790          # binds 127.0.0.1; refuses to start without a token

Authenticate with a header, which keeps the secret out of URLs, browser history and proxy logs:

Authorization: Bearer $FINEYE_MCP_TOKEN

If your client has no header field, the token also works as the URL path (https://<host>/<token>). A wrong credential gets a 404, never a 403 — a probe should not learn that anything lives there.

The listener is plain HTTP on localhost by design: put a TLS front in front of it — Cloudflare Tunnel, a Tailscale Funnel, a reverse proxy on a VPS, whatever you already run — and point the client at https://<your-host>/mcp.

Think before you do this. It puts a live endpoint to your real finances on the internet, guarded by one token. Prefer FINEYE_READONLY=1 for anything left running unattended, keep the token out of screenshots, and rotate it by rewriting the file and restarting the server.

CLI

The same operations, for humans and shell scripts.

fineye whoami
fineye accounts [--archived] [--json]
fineye networth [--history] [--json]
fineye transactions [--from <date> --to <date> --account <acc> --category <cat> --search <q>] [--json]
fineye analytics [--month YYYY-MM] [--all] [--leaf] [--by-tag] [--by-merchant --top <n>] [--json]
fineye budget [--month YYYY-MM] | fineye budget history [--limit <n>]
fineye export [--format csv|json] [--from --to] [--out <file>]

fineye add expense <amount> --account <acc> [--category --desc --date --fee]
fineye add transfer <amount> --from <acc> --to <acc> [--to-amount <n>]
fineye tx edit <id> [--desc --category --date --hold]
fineye bulk recategorize <filters> --set-category <cat> [--apply]
fineye rule add --merchant "<exact description>" --mcc <code> --category <cat>

Amounts are in the account's own currency (decimal major units, e.g. 42.50). add transfer writes the same magnitude to both legs, matching the app; pass --to-amount when the destination actually received a different number — the CLI never converts at a rate of its own.

fineye ui opens a terminal dashboard: accounts and balances, net worth with a 30-day sparkline, transactions for the selected account, and a spend-by-category chart.

For agents driving the CLI rather than the MCP server, fineye skill --install writes an agent skill to ~/.claude/skills/use-fineye/SKILL.md.

How it works

FinEye is a Capacitor app on a Supabase backend. This client speaks to the same PostgREST tables and RPCs the app does, authenticating as your own Google account over PKCE OAuth (email OTP as a fallback). Row-level security means you only ever see your own rows.

The layering is deliberate:

src/domain/*      pure logic: valuation, analytics, transaction shapes, bulk selection
src/client.ts     the only thing that talks HTTP — and where the allow-lists live
src/mcp/*         the MCP surface: tools, resources, instructions, transports
src/commands/*    the CLI surface over the same domain
src/skill/*       data-model semantics, shared by the MCP instructions and the CLI skill

Both surfaces call the same domain functions, so the CLI and the MCP server cannot disagree about what a transfer is or which rows count as spending.

A few facts about the data that the domain layer encodes, because getting them wrong produces confident wrong answers: a transaction has no top-level amount (sum movements[].sum, negative for expenses); each account has its own currency, so raw sums are not comparable; a two-leg movement is always a transfer between your own accounts; and installment plans carry future legs flagged scheduled, which analytics excludes from what you have actually spent.

Development

npm run typecheck && npm run lint && npm test && npm run build
npm run format

The test suite spawns the built binary and speaks real MCP over stdio, so transport wiring is covered rather than assumed.

License

MIT — see LICENSE.