moneylover-kit

Unofficial Money Lover client, CLI and MCP server. Full transaction CRUD, lending, and a documented API — from your email and password, with nothing else to set up.

Not affiliated with Money Lover or Finsify. Money Lover has no public API; this talks to the same endpoints its own apps use.

Why this exists

Other Money Lover clients can create and read transactions. None of them can update or delete one, because the wire format is a full replace — a naive edit silently wipes the people, the event, the exclude-from-report flag and the reminder attached to the row. This rebuilds every write from the live row, so an edit changes only what you asked it to.

It also documents the parts that cost real time to work out: why a wrong category id hangs for two minutes instead of erroring, why an empty result isn't an empty account, and why logging in twice can sign you out of your own phone. See docs/traps.md.

Install

npm install -g @notsuhas/moneylover-kit    # or npx @notsuhas/moneylover-kit

To run it from source instead, clone and build — npm install -g github:notsuhas/moneylover-kit does not work, because npm skips devDependencies when preparing a git dependency and leaves no compiler to build with:

git clone https://github.com/notsuhas/moneylover-kit && cd moneylover-kit
npm ci && npm run build && npm install -g .

Then set your credentials:

export MONEYLOVER_EMAIL="[email protected]"
export MONEYLOVER_PASSWORD="…"

CLI

moneylover login                 # once — mints and caches a token
moneylover wallets               # names and balances
moneylover categories            # what you can write to
moneylover list --note coffee --from 2026-01-01 --limit 10

moneylover add  --wallet Cash --category Groceries --amount -480 --note "DMart"
moneylover edit <id> --note "DMart, cleaning supplies"
moneylover rm   <id>

Wallets and categories too:

moneylover add-wallet   --name Travel --currency 11
moneylover add-category --name Supplements --all-wallets --parent "Health"
moneylover edit-category --category Supplements --name Vitamins
moneylover rm-category  --category Vitamins

--all-wallets and --parent need --backend mobile: a category that spans every wallet, or nests under another, lives in a layer the web API doesn't model.

Amounts are signed: -480 is spent, 4500 is earned. Money Lover stores the direction in the category rather than the amount, so a sign that disagrees with the category is rejected instead of quietly corrected.

--json on any command gives machine-readable output.

Lending

Money Lover tracks money between people in four of its own system categories. This wraps them, so the app's debt view sees what you record:

moneylover lend    --person Sam --amount 5000 --wallet Savings
moneylover collect --person Sam --amount 3000 --wallet Current
moneylover lending

person                          lent   collected   outstanding     you owe
Sam                          5000.00     3000.00       2000.00        0.00
Jordan                        800.00      800.00          0.00      450.00

The wallet is per leg, so lending from one account and being paid back into a different one is normal — the balance is tracked against the person, not the account. borrow and repay are the mirror for money you owe.

MCP server

Two transports. Both expose the same eight tools: list_wallets, list_categories, search_transactions, add_transaction, edit_transaction, delete_transaction, record_lending, lending_summary.

Managing wallets, categories and events is opt-in, behind two flags: MONEYLOVER_MCP_ALLOW_STRUCTURE=1 for creating and editing them, and MONEYLOVER_MCP_ALLOW_DELETE=1 for delete_wallet and delete_category. A rename can be typed back; deleting a wallet takes every transaction in it and neither API has an undo, which is why it is its own switch.

Local, for Claude Desktop / Cursor — add to your MCP config:

{
  "mcpServers": {
    "moneylover": {
      "command": "npx",
      "args": ["-y", "-p", "@notsuhas/moneylover-kit", "moneylover-mcp"],
      "env": {
        "MONEYLOVER_EMAIL": "[email protected]",
        "MONEYLOVER_PASSWORD": "…"
      }
    }
  }
}

Remote, over HTTP — for running it somewhere and pointing a client at it:

MCP_TOKEN=$(openssl rand -hex 32) moneylover-mcp-http   # POST /mcp, GET /health

It refuses to start without MCP_TOKEN. This endpoint can create and delete transactions in a real account; an unauthenticated port is never the right default.

In Docker — a Dockerfile and compose.yaml are in the repo:

cp .env.example .env      # email, password, and an MCP_TOKEN
docker compose up -d      # POST localhost:8790/mcp

Mount something persistent at /config, as the compose file does. That is where the token cache lives, and without it every restart spends one of the account's device slots.

Full setup notes, including how to keep an agent from doing something irreversible: docs/mcp.md.

Library

import { createClient } from "@notsuhas/moneylover-kit";

const ml = createClient();

await ml.wallets();
await ml.transactions({ note: "coffee", from: "2026-01-01" });
await ml.addTransaction({
  wallet: "Cash",
  category: "Groceries",
  amount: -480,
});
await ml.lending("Sam");

The CLI and the MCP server are both thin layers over this, so they cannot do anything the library can't.

One mobile session

When the Android OAuth client is configured, every normal read and transaction or category write uses the mobile API. Wallet balances are derived exactly as the app derives them: sum the synced rows in integer minor units and exclude future-dated transactions. The result matched the web API for every wallet on a live 11,239-row account.

The first run stores the full sync beside the token cache. Later reads pull only changes since that checkpoint, then balance, transaction and edit calls share the local mirror. This is the same shape as the app's local sync database.

To enable mobile:

export MONEYLOVER_MOBILE_CLIENT="…"
export MONEYLOVER_MOBILE_SECRET="…"

Those are the Android app's own credentials, hardcoded in every copy of it. They aren't a secret of yours, but they're not published here — a searchable public copy is what gets them rotated, which would break every unofficial client at once. docs/api.md explains how to get them.

Without those two values the client fails clearly; it never falls back to a web login. --backend web remains an explicit diagnostic escape hatch. Wallet creation, rename and deletion use the mobile sync protocol too.

Use MONEYLOVER_MOBILE_TOKEN if you supply a token directly. Normally the cached rotating refresh token is safer because it self-renews.

The one thing to know before you start

A Money Lover account allows only a handful of devices to hold a token at once — five, currently — and every login registers another one. Nothing gets kicked off when you reach the limit; instead the next login is refused, with "Maximum device limit reached. Please log out to continue." So you don't lose data — you lose the ability to sign in at all, including on a replacement phone, until you log out from a device you still have.

So this caches your token under ~/.config/moneylover-kit/ and renews it without registering another device, so a service maintains itself with no further logins. The mobile route is non-standard: the Android app sends an empty body to oauth.moneylover.me/refresh-token with the refresh token as Bearer auth.

Set MONEYLOVER_ACCESS_TOKEN to supply a token directly and never log in.

Environment

| | | | ------------------------------------------------------- | --------------------------------- | | MONEYLOVER_EMAIL · MONEYLOVER_PASSWORD | credentials | | MONEYLOVER_ACCESS_TOKEN | use this token, never log in | | MONEYLOVER_BACKEND | force web or mobile | | MONEYLOVER_MOBILE_CLIENT · MONEYLOVER_MOBILE_SECRET | required by the mobile backend | | MONEYLOVER_CONFIG_DIR | where the token cache lives | | MCP_TOKEN · MCP_PORT · MCP_HOST | HTTP MCP transport | | MONEYLOVER_MCP_ALLOW_STRUCTURE | MCP: wallet/category/event writes | | MONEYLOVER_MCP_ALLOW_DELETE | MCP: wallet/category deletes |

Docs

• docs/api.md — both APIs: auth, endpoints, item shapes
• docs/traps.md — everything that cost a day to work out
• docs/mcp.md — wiring the MCP server into a client
• spec/ — OpenAPI spec for the web API, plus observed schemas

Contributing

See CONTRIBUTING.md. npm run verify runs typecheck, lint, formatting and the codebase-health gate.

Licence

MIT. Use it against your own account.