zerro-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
zerro-mcp
An MCP server for the envelope budget of Zerro, the open-source web client for ZenMoney. An agent can read and change the budget the way Zerro shows it — envelopes, "To be assigned", overspend, goals — without a browser.
Zerro keeps its budget inside ZenMoney: assignments, goals and envelope
settings are JSON documents in reminders of a hidden account
🤖 [Zerro Data], and everything else (leftovers, available, "To be
assigned") is computed from transactions. This server does not reimplement
that math: it runs Zerro's own calculation core, vendored from the Zerro
repository (see NOTICE.md), so the numbers match Zerro.
This is not ZenMoney's native category budget (what ZenMoney apps show). For ZenMoney data itself — accounts, transactions, categories — use a ZenMoney MCP server.
Tools
Reading:
Tool | What it gives |
| Envelopes of a month in Zerro's groups: leftover, assigned, activity, available — own and with children — and the goal |
| Month totals: money in the budget, "To be assigned" and its state, overspend, assigned in future months |
| Transactions behind an envelope's activity, routed as Zerro routes them |
| Goals in effect for a month, what each envelope still needs, progress |
| Pull from ZenMoney now |
Writing (only with ZERRO_MCP_WRITE=1):
Tool | What it does |
| Set an envelope's total "Assigned" for a month, as typing it in Zerro |
| Move an amount between envelopes or to/from "To be assigned" |
| Cover overspend of one envelope or all of them |
Envelopes are named by id (tag#…, payee#…, merchant#…, account#…) or by
exact name; an ambiguous name returns the candidates. Months are YYYY-MM
within the range Zerro has.
How writing works
ZenMoney has no compare-and-swap: a document is replaced by whichever copy arrives with the newer timestamp, and Zerro writes a month's budget as one document. So each write tool works in two calls:
Without
confirmit pulls, compiles the change with Zerro's own action (the same code the buttons in Zerro run), applies it in memory and returns the result — what changes, the envelopes after, "To be assigned" after — and a token.With
confirm: <token>it pulls again and recomputes. If anything moved (new transactions, rates, someone else's edit), the token no longer matches and you get a new preview instead of a write. Otherwise it sends the change, pulls, and checks that every row sent is on the server as sent and that every month's assignments are exactly as previewed.
The answer's status says how it ended: confirmed; written_figures_changed
(the write is exactly as planned, but other data moved the figures meanwhile —
the answer shows the current ones); unconfirmed or unverified (the server
does not show the planned state, or could not be checked — see the journal).
While a write runs, nobody should edit the budget in Zerro, and an open Zerro
tab must not hold unsent changes. Writes are refused when Zerro's stored
documents look damaged (the same month stored twice, a malformed payload).
Each write leaves a private journal in ZERRO_MCP_STATE_DIR/journal with the
rows as they were before, what was sent and how it ended; a journal still named
*.open.json is a write whose outcome was not confirmed. A lost answer is
never retried automatically: the server pulls and reports what it sees.
Enable writing on one machine only. Processes on that machine take turns
through a lock file in ZERRO_MCP_STATE_DIR; a lock left by a process that
died mid-write is not taken over automatically — check the budget and the open
journal, then delete the lock file.
Related MCP server: actual-mcp
Setup
Get a ZenMoney token at https://zerro.app/token.
{
"mcpServers": {
"zerro": {
"command": "npx",
"args": ["-y", "--package=https://github.com/oviron/zerro-mcp/releases/download/v0.1.2/zerro-mcp-0.1.2.tgz", "zerro-mcp"],
"env": { "ZENMONEY_TOKEN": "…" }
}
}
}Or from a clone: npm ci && npm run build, then run node build/index.js.
Variable | Default | Meaning |
| — | ZenMoney API token, required |
|
| or |
|
| Seconds to wait for ZenMoney |
|
| Tools pull first when data is older than this many seconds |
| your ZenMoney currency | Currency for month totals (Zerro keeps its own choice in the browser) |
| off |
|
|
| Write lock and journals |
Requires Node.js 20 or newer. The server keeps ZenMoney data in memory only.
Development
npm ci
npm run typecheck
npm test # fixtures and a fake ZenMoney server; no network
npm run build # one self-contained build/index.jsThe core lives in vendor/zerro-core, unchanged from upstream; src/core.ts
is the only module that imports it. Updating it: copy src/zerro-core from a
newer Zerro commit (without tests), update NOTICE.md, run the checks, and
compare a few envelopes and the month summary with zerro.app on the same data.
License
GPL-2.0-only, the license of Zerro, whose core this server includes.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Multi-currency budgeting: read and update your accounts, transactions, categories and budgets.
The budget app your AI agent can use. Check budgets and log spending, with no bank logins.
Review EnvelopeBudget data and optionally categorize transactions with explicit scoped permissions.
Ask about your Waypoint Budget spending, budgets, goals and accounts. Read-only.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables users to interact with YNAB budgets, accounts, transactions, and more through a comprehensive set of tools with batch operations, deterministic analysis, and undo support.2693 npm6MIT
- AlicenseBqualityDmaintenanceEnables agents to read and edit budgets in Actual Budget via natural language, with a safety layer that requires confirmation for destructive actions.28494 npm2MIT
- AlicenseAqualityCmaintenanceProvides a read-only interface to YNAB budget data, allowing AI assistants to inspect budgets, accounts, categories, transactions, and more. Includes an experimental guarded write workflow for category assignments.1012 npmMIT
- AlicenseAqualityBmaintenanceLets an AI agent read a YNAB budget and ask plain-language questions about it — where money went, what still needs a category, whether an account matches the bank, and when money would run out. Changes such as categorising, splitting or budgeting are read-only by default, and every write is previewed, explicitly confirmed, and undoable.19134 PyPI6MIT