mcp-server-zenmoney
This MCP server lets an AI agent read, analyze, and update a user's ZenMoney finances through natural-language tool calls.
Get a financial overview: net worth, balances, monthly income/expenses, upcoming operations, and data freshness.
Inspect accounts, categories, payees, planned operations, budgets, and per-person debts.
Search and filter transactions by dates, type, accounts, categories, payee, text, amount, currency, and deletion status.
Summarize spending or income by category, parent category, payee, account, day/week/month/year, or cash flow.
Suggest categories and merchants for payees using ZenMoney suggestions and user history.
Sync data from ZenMoney, including full re-download.
Create, edit, delete, and restore transactions, with dry-run previews, auto-categorization, and duplicate warnings.
Manage categories, monthly budgets, accounts, and account balance reconciliation.
Use built-in workflows for monthly review, transaction categorization, and budget planning.
Run locally against the official ZenMoney API, optionally in read-only mode or HTTP mode, with token and cache privacy controls.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-server-zenmoney how much did I spend on groceries this month?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
💸 ZenMoney MCP
Talk to your money. Let Claude, Cursor, Codex or any MCP agent read, analyze and update your ZenMoney (Дзен-мани) finances in plain language.
Example conversation:
You: How did October go? Anything unusual compared to September?
Agent: calls
summarize_transactions,get_budget→ Restaurants went 40% over budget, mostly in the last week. Taxi doubled after you started commuting by Yandex Go. Groceries were flat. Want me to raise the Restaurants budget for November or set up a category for the commute?
✨ Why
🔍 Ask anything. Balances, net worth, where the money went, budget status, who owes whom, what's due next week.
✍️ Record by talking. "Magnum 12 450 KZT from Kaspi Gold, groceries." Categories are filled in from your history, and duplicates trigger a warning.
📊 Budgets and reviews. Built-in
monthly_review,categorize_transactionsandplan_budgetworkflows.🛡️ Safe by default. Read-only mode,
dry_runpreviews, soft deletes with restore, confirmation hints on destructive tools.🔒 Private. Runs on your machine and talks only to the official ZenMoney API. Your token never touches disk.
Unofficial project, not affiliated with ZenMoney or Zerro.
Related MCP server: LunchMoney MCP Server
🪄 Install with one prompt
Paste this into your coding agent (Claude Code, Codex, Cursor, omp, …):
Install the ZenMoney MCP server for me: https://github.com/krax1337/mcp-server-zenmoney
Follow the "Agent setup guide" in its README.The agent checks Node, has you save the token to a private file (it never asks you to paste the token into chat), verifies it, and registers the server in its own config.
Check that
node --versionis 22 or newer. If it isn't, stop and tell the user.Ask the user to open https://zerro.app/token, log in with their ZenMoney account and save the token themselves with:
mkdir -p ~/.config && umask 077 && printf '%s' 'PASTE_TOKEN_HERE' > ~/.config/zenmoney-tokenDo not ask for the token in chat, and do not write it into any config file.
Verify the token:
ZENMONEY_TOKEN_FILE=~/.config/zenmoney-token npx -y mcp-server-zenmoney --checkExpect
OK: <login>, main currency …. On exit code 1, show the user the reason and stop.Ask the user whether the agent may change their data or should be read-only. For read-only, add
"ZENMONEY_READ_ONLY": "true"toenv(or-e ZENMONEY_READ_ONLY=truefor Claude Code).Register the server in your own MCP config, using the absolute path of the token file:
Claude Code:
claude mcp add zenmoney -e ZENMONEY_TOKEN_FILE=$HOME/.config/zenmoney-token -- npx -y mcp-server-zenmoneyClients with an
mcpServersJSON file (Claude Desktop, Cursor, omp, …):"zenmoney": { "command": "npx", "args": ["-y", "mcp-server-zenmoney"], "env": { "ZENMONEY_TOKEN_FILE": "/home/<user>/.config/zenmoney-token" } }
Tell the user to restart or reload MCP servers, then try: "Give me an overview of my finances."
🚀 Manual install
Requirements: Node.js >= 22.
Get a token: open https://zerro.app/token, log in with your ZenMoney account and copy the token.
Check it:
ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --checkprintsOK: <login>, main currency …, N active accounts, M transactions(exit code 1 with the reason otherwise).Add it to your agent:
Claude Code
claude mcp add zenmoney -e ZENMONEY_TOKEN=YOUR_TOKEN -- npx -y mcp-server-zenmoneyClaude Desktop / Cursor / most MCP clients (claude_desktop_config.json, ~/.cursor/mcp.json, …)
{
"mcpServers": {
"zenmoney": {
"command": "npx",
"args": ["-y", "mcp-server-zenmoney"],
"env": { "ZENMONEY_TOKEN": "YOUR_TOKEN" }
}
}
}omp: user-wide config ~/.omp/agent/mcp.json (or per project .omp/mcp.json), inside mcpServers:
"zenmoney": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-server-zenmoney"],
"env": { "ZENMONEY_TOKEN": "${ZENMONEY_TOKEN}" }
}omp expands ${VAR} placeholders, so the token can stay in your shell environment. Then /mcp reload.
Without a token the server still starts, and every tool explains how to configure one.
Keeping the token out of config files
umask 077 && printf '%s' 'YOUR_TOKEN' > ~/.config/zenmoney-tokenThen use "env": { "ZENMONEY_TOKEN_FILE": "~/.config/zenmoney-token" } instead of ZENMONEY_TOKEN.
Read-only
Add "ZENMONEY_READ_ONLY": "true" to env, or --read-only to args. Write tools are then not registered at all.
HTTP mode
ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --http --port 3000MCP endpoint (Streamable HTTP):
http://127.0.0.1:3000/mcp;GET /healthreturns{"ok":true}; any other path is 404.Default bind is
127.0.0.1. Loopback binds (127.0.0.1,localhost,::1) apply Host/Origin validation against DNS rebinding.Any other
--host/MCP_HTTP_HOSTis refused unlessMCP_HTTP_TOKENis set. When set (on any bind), clients must sendAuthorization: Bearer <MCP_HTTP_TOKEN>, otherwise they get 401. It is a single-user server: whoever has that token has your ZenMoney access, so keep it on a private network.
💬 Things to ask
"How did October go? Biggest categories and anything unusual compared to September."
"Add: Magnum 12 450 KZT today from Kaspi Gold, groceries."
"Recategorize all Yandex Go rides from last month to Transport / Taxi."
"Copy this month's budgets to next month, but raise Restaurants to 80 000."
"Who owes me money, and how much in total?"
"What payments are scheduled for the next two weeks?"
"My cash wallet actually has 23 000; fix the balance."
🧰 Tools
Read (always registered, annotated readOnlyHint):
Tool | Purpose |
| Start here: today's date, main currency, net worth, account balances, this month's income/expenses, upcoming planned operations, data freshness |
| Accounts with balances (also in main currency), credit limits, bank and flags |
| Category tree with kind (expense/income/both) and 12-month usage counts |
| Known payees ranked by use, with last date and usual category |
| Filtered, paginated transaction search plus income/expense totals of all matches |
| Aggregate by category, parent category, payee, account or day/week/month/year; |
| Monthly budget vs. actual, remaining, % used and still-planned operations per category |
| Planned / recurring operations still pending in a date range, with expected totals |
| Per-person debt balances (positive = they owe you); optionally a person's debt transactions |
| Category/merchant suggestions for payee names from ZenMoney and your own history |
| Pull changes from ZenMoney now; |
Write (not registered in read-only mode):
Tool | Purpose |
| Record up to 50 expenses, incomes, transfers or debt operations; auto-categorizes, warns about duplicates |
| Edit amount, account, category, payee, comment, date, original amount; transfer destination. Type cannot change |
| Soft-delete transactions by id |
| Bring deleted transactions back (as copies with new ids) |
| Create a category or subcategory (one nesting level) |
| Rename, move, change kind, budget inclusion, mandatory flag, archive |
| Delete a category, moving its transactions and planned operations to |
| Set exact monthly budgets per category, |
| Create a cash, card, checking or e-money account |
| Rename, archive, include/exclude from balance, savings flag, credit limit |
| Match a real balance by recording a correction income/expense |
Write tools carry MCP annotations: creating tools are non-destructive (destructiveHint: false); editing/deleting tools are destructiveHint: true, so clients that honor hints can ask for confirmation.
create_transactions, update_transactions, delete_transactions, delete_category and set_budgets accept dry_run: true: they resolve everything and return the would-be result (for updates: before/after per transaction) without sending anything to ZenMoney.
Prompts
Clients that support MCP prompts (e.g. as slash commands) get three workflows that only orchestrate the tools above:
Prompt | Arguments | What it does |
|
| Income, spending vs. previous month, budget status, large transactions, upcoming payments, suggestions |
|
| Proposes categories for uncategorized transactions, applies after confirmation (dry run first) |
|
| Proposes budgets from the last three months and planned payments, applies with |
🔒 Data, privacy and sync
The server keeps a local replica of your ZenMoney database, synced through the official API v8 (
POST /v8/diff/, plusPOST /v8/suggest/for categories): a full download on first use, incremental diffs afterwards. Data older thanZENMONEY_SYNC_TTLseconds is refreshed automatically before a tool runs;syncforces it.The replica is persisted to
<cache dir>/snapshot-<hash>.json(directory created0700, file0600). The filename is a hash of token and API origin; the token itself is never written to disk. The snapshot does contain your financial data. SetZENMONEY_CACHE=offto keep everything in memory.API origin:
https://api.zenmoney.rufirst; if it rejects the token before any request has succeeded,https://api.zenmoney.appis tried.ZENMONEY_API_URLpins a single origin.HTTP 401 from ZenMoney means the token is no longer valid: get a fresh one at https://zerro.app/token.
"Today" and default dates use the process time zone; set
TZ(e.g.TZ=Asia/Almaty) in the server'senvif the agent host runs in a different zone.Snapshots of tokens you no longer use stay in the cache directory; delete old
snapshot-*.jsonfiles after rotating a token.Logs go to stderr only.
Variable / flag | Default | Meaning |
| — | ZenMoney API token from https://zerro.app/token |
| — | File containing the token (used when |
|
|
|
|
| Seconds before data is re-synced on the next tool call |
|
| Snapshot cache directory |
| on |
|
|
| Pin a single API origin |
|
|
|
|
| HTTP bind address |
|
| HTTP port |
| — | Bearer token HTTP clients must send; required for non-loopback binds |
| — | Sync once with the configured token, print a one-line summary and exit |
| — | Print usage / version |
CLI flags take precedence over the corresponding environment variables.
Amounts are always positive;
typegives the direction:expense,income,transfer(between own accounts),debt_out(money given to a person: lending or repaying),debt_in(money received: borrowing or being repaid).Accounts and categories are referenced by name (case- and emoji-insensitive, unique substrings work),
"Parent / Child"category paths, or ids. Accounts can also be referenced by card last digits (4+).Currencies are ISO codes (
RUB,USD,KZT, ...). Dates areYYYY-MM-DD.Query tools accept
period:today,yesterday,this_week,last_week,this_month,last_month,this_quarter,last_quarter,this_year,last_year,last_7_days,last_30_days,last_90_days,last_12_months(weeks start Monday;date_from/date_tooverride either end).Reports are in the main currency at ZenMoney's current exchange rates and, like ZenMoney, count only in-balance accounts unless asked otherwise. Transfers and debts are excluded from summaries. The totals returned by
list_transactionsfollow the same rules (in-balance, not deleted), even when the listed transactions include off-balance or deleted ones.A missing expense/income category on new transactions is filled from this payee's history first, then from the ZenMoney suggestion service (only live categories of the right kind). A new transaction matching an existing one (same date, type, account and amount) produces a duplicate warning; it is still recorded.
update_transactionscategoryreplaces the main category and keeps secondary tags;nullleaves the transaction uncategorized. Moving a transaction to an account in another currency requires the newamount. Changing onlyamountof a same-currency transfer updates both sides unless the received amount differed (a fee), which is kept.Every write syncs with ZenMoney first and runs one at a time, so edits made in the app moments earlier are not overwritten and parallel tool calls cannot clobber each other. References to categories/merchants deleted in the app are dropped from pushed objects instead of failing the whole batch.
If ZenMoney accepts a write but the answer is lost (timeout), the tool says the change may or may not have been saved; the next call re-syncs, so a retry gets a duplicate warning instead of silently doubling.
Deletes are soft. ZenMoney cannot undelete in place, so
restore_transactionsre-creates each transaction under a new id; restoring the same transaction again is a no-op that points at the existing copy.Budgets:
set_budgetssets an exact amount (lock on);0removes the budget. Budgets without the lock (set in the app) also include the month's planned operations, as in ZenMoney. The profile's month start day is honored. Rollover between months is not modelled.Zerro's hidden
🤖 [Zerro Data]account and the reminders attached to it are ignored everywhere.
⚠️ Limitations
Planned (recurring) operations can be read but not created or edited.
Loan and deposit accounts cannot be created; bank-synced accounts are created by ZenMoney itself.
Balances are not edited directly;
adjust_account_balancerecords a correction transaction.Currency conversions in reports use current exchange rates, not historical ones.
Zerro's envelope budget rollover is not computed.
🇷🇺 По-русски
MCP-сервер для Дзен-мани: ИИ-агент (Claude, Cursor, Codex и др.) видит счета и балансы, ищет операции, строит отчёты, ведёт бюджеты и долги, добавляет и редактирует операции. Работает локально через официальный API, токен берётся на https://zerro.app/token. Быстрая установка: вставьте агенту промпт из раздела Install with one prompt. Есть режим только для чтения (ZENMONEY_READ_ONLY=true).
🛠️ Development
git clone https://github.com/krax1337/mcp-server-zenmoney && cd mcp-server-zenmoney
npm install # also builds dist/
npm run typecheck # tsc --noEmit
npm test # vitest; offline, against an in-repo fake ZenMoney server in test/
node dist/index.js # run the local buildReleases: bump version in package.json and server.json, then push a vX.Y.Z tag. The Publish workflow tests the code and stages the version on npm via Trusted Publishing (no token, with provenance). A maintainer approves it with 2FA on npmjs.com (Staged Packages tab), then runs the Publish workflow manually (gh workflow run publish.yml), which sees the version live and publishes it to the MCP Registry as io.github.krax1337/mcp-server-zenmoney.
src/index.ts— entry point, stdio and HTTP transportssrc/config.ts— environment variables and CLI flagssrc/server.ts— MCP server and agent instructionssrc/prompts.ts— MCP prompts (monthly_review,categorize_transactions,plan_budget)src/tools/— MCP tools (read.ts,write.ts, shared schemas and context)src/zenmoney/— API client (api.ts), sync store and cache (store.ts), ledger semantics (ledger.ts), analytics (analytics.ts), write builders (writes.ts), dates and types
License
MIT. If this saves you time, a ⭐ helps others find it.
Available Tools
22 toolsadjust_account_balanceReconcile account balanceAIdempotent
Make an account balance match reality by recording the difference as an income or expense correction transaction (computed against freshly synced data).
Inputs: account (required), actual_balance (required), date, comment, +1 more.
create_accountCreate accountB
Create a cash, card, checking or e-money account. Bank-synced accounts are created by ZenMoney itself.
Inputs: title (required), type, balance, savings, +3 more.
create_categoryCreate categoryA
Create a category, optionally as a subcategory of a top-level category (ZenMoney allows one nesting level).
Inputs: title (required), kind, parent, required.
create_transactionsAdd transactionsA
Record one or more transactions (expense, income, transfer between own accounts, debt_out / debt_in with a person). Amounts are positive in the account currency. Without a category, one is picked from this payee's history or ZenMoney suggestions (auto_categorize). Returns the created transactions, updated balances and possible-duplicate warnings.
Inputs: transactions (required), dry_run, auto_categorize.
delete_categoryDelete categoryADestructiveIdempotent
Delete a category. Its transactions and planned operations are moved to move_to (merge categories) or, with uncategorize=true, left without this category. Subcategories must be moved or deleted first.
Inputs: category (required), dry_run, move_to, uncategorize.
delete_transactionsDelete transactionsADestructiveIdempotent
Delete transactions by id (soft delete; restore_transactions brings them back).
Inputs: ids (required), dry_run.
get_budgetMonthly budget statusBRead-only
ZenMoney budget for a month: per category budget, actual, remaining, % used and still-planned operations, with subcategories and totals, in the main currency. Uses the profile's month start day. Rollover between months is not modelled.
Inputs: side, month.
get_overviewFinancial overviewARead-only
Start here. Returns today's date, the user's main currency, net worth, active account balances, this month's income/expenses with top categories, upcoming planned operations and data freshness.
Inputs: no named parameters.
list_accountsList accountsARead-only
Accounts with balances, currency, credit limit, bank and flags. balance_main is the balance converted to the main currency. Totals cover in-balance accounts. Debt bookkeeping is in list_debts.
Inputs: types, search, include_archived.
list_categoriesList categoriesARead-only
Category tree (ZenMoney "tags"; one nesting level) with ids, kind (expense/income/both) and number of uses in the last 12 months. Use names, "Parent / Child" paths or ids elsewhere.
Inputs: kind, search, include_archived.
list_debtsDebts by personARead-only
Who owes whom: per-person debt balances from debt operations (positive = they owe you, negative = you owe them), per currency and in the main currency. Pass person to also get their debt transactions.
Inputs: person, include_settled.
list_payeesList payeesARead-only
Known payees/merchants ranked by number of transactions, with last date and the category usually used for them. Useful for consistent categorization and payee spelling.
Inputs: limit, search.
list_plannedPlanned operationsARead-only
Scheduled / recurring operations (ZenMoney reminders) that are still planned in a date range, with recurrence, overdue and forecast flags, plus expected expense/income totals.
Inputs: date_to, date_from, include_forecast.
list_transactionsSearch transactionsARead-only
Find transactions with filters (dates/period, type, accounts, categories incl. subcategories, payee, free text, amount, currency). Newest first by default, paginated. Also returns income/expense totals of all matches in the main currency (in-balance accounts only, like ZenMoney reports), so "how much did I spend on X" needs only this call (or summarize_transactions for breakdowns).
Inputs: ids, sort, limit, payee, +13 more.
restore_transactionsRestore deleted transactionsAIdempotent
Bring back deleted transactions (find them with list_transactions include_deleted=true). ZenMoney cannot undelete in place, so each comes back as a copy with a new id; already-restored ones are skipped.
Inputs: ids (required).
set_budgetsSet monthly budgetsADestructiveIdempotent
Set exact monthly budget amounts (main currency) per category, for "total" (overall monthly budget) or "uncategorized". 0 removes that budget. Batch-friendly: e.g. copy last month's budgets to next month.
Inputs: budgets (required), dry_run.
suggest_categorySuggest category for payeesARead-only
Category and merchant suggestions for payee names, from ZenMoney's suggestion service and from this user's own history.
Inputs: payees (required).
summarize_transactionsSpending / income reportARead-only
Aggregate expenses and/or income by category, parent category, payee, account or time (day/week/month/year) with totals, counts and shares. measure=both gives income, expense and net per group (cash flow). Transfers and debts are excluded; amounts are converted with current rates. By default only in-balance accounts count, like ZenMoney reports.
Inputs: top, payee, types, period, +13 more.
syncSync with ZenMoneyARead-onlyIdempotent
Pull the latest changes from ZenMoney now (tools already auto-sync when data is older than the configured TTL). full=true re-downloads everything.
Inputs: full.
update_accountEdit accountADestructiveIdempotent
Rename, archive/unarchive, include in or exclude from balance, mark as savings, or change the credit limit. To fix a balance use adjust_account_balance.
Inputs: account (required), title, savings, archived, +2 more.
update_categoryEdit categoryBDestructiveIdempotent
Rename, move (parent null = top level), change kind, budget inclusion, mandatory flag or archive a category.
Inputs: category (required), kind, title, parent, +3 more.
update_transactionsEdit transactionsADestructiveIdempotent
Change one or more existing transactions: amount, account, main category (null = uncategorized), payee, comment, date, original currency amount; transfers also to_account / to_amount. The type cannot change (delete and re-create instead). Use list_transactions to find ids.
Inputs: updates (required), dry_run.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 22 tools
Most tools target clearly distinct resources and actions, and descriptions explicitly disambiguate overlaps (e.g., list_transactions vs. summarize_transactions). However, several tools provide overlapping aggregate views (get_overview, list_transactions totals, get_budget, summarize_transactions) that an agent could confuse for a given reporting question.
The set follows a consistent snake_case verb_noun pattern (list_accounts, create_transactions, update_category, delete_transactions, etc.). The lone bare verb 'sync' is a minor deviation, but the convention is otherwise predictable and readable.
22 tools is on the heavy side for the 3-15 sweet spot, but each tool maps to a distinct finance operation (accounts, categories, transactions, budgets, planned, debts, analytics) and the domain genuinely supports this breadth. It is slightly over-scoped rather than bloated.
Coverage is strong: full CRUD for transactions (including restore), categories, and accounts, plus budgeting, debt, and analytics views. Gaps remain for planned/recurring operation creation and editing (only list_planned exists) and payee management (only list/suggest), which agents must work around.
Maintenance
Related MCP Connectors
Personal finance for AI agents: accounts, budgets, goals, 9-strategy debt payoff, reports. OAuth 2.1
Read-only personal finance for AI agents: budgets, receipts, net worth, bills. OAuth 2.1.
Connect AI agents to bank accounts, transactions, balances, and investments.
Personal finance ledger for AI agents — query spending, track bills, forecast cash flow.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables AI agents to interact with your Lunch Money personal finance data, providing tools for managing transactions, categories, budgets, assets, and accounts.1541 npmISC
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to access and manage personal finance data through LunchMoney's API, including transactions, budgets, categories, tags, recurring items, accounts, crypto holdings, and balance history. Provides full CRUD operations, advanced filtering, and automated financial insights for personal finance workflows.41 npm-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to access and manage personal finance data through LunchMoney’s API, including transactions, categories, tags, budgets, recurring items, accounts, crypto, and balance history. It supports full CRUD, filtering, bulk operations, attachments, and token-efficient responses for automated financial insights.41 npm-
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants and MCP clients to access and manage personal finance data through LunchMoney's API, including transactions, budgets, categories, tags, recurring items, accounts, crypto, and balance history.41 npmMIT