Skip to main content
Glama
mcp-server-zenmoney

mcp-server-zenmoney

by krax1337

💸 ZenMoney MCP

Talk to your money. Let Claude, Cursor, Codex or any MCP agent read, analyze and update your ZenMoney (Дзен-мани) finances in plain language.

CI npm MCP Registry Node License: MIT

Install in Cursor Install in VS Code

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_transactions and plan_budget workflows.

  • 🛡️ Safe by default. Read-only mode, dry_run previews, 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.

  1. Check that node --version is 22 or newer. If it isn't, stop and tell the user.

  2. 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-token

    Do not ask for the token in chat, and do not write it into any config file.

  3. Verify the token:

    ZENMONEY_TOKEN_FILE=~/.config/zenmoney-token npx -y mcp-server-zenmoney --check

    Expect OK: <login>, main currency …. On exit code 1, show the user the reason and stop.

  4. Ask the user whether the agent may change their data or should be read-only. For read-only, add "ZENMONEY_READ_ONLY": "true" to env (or -e ZENMONEY_READ_ONLY=true for Claude Code).

  5. 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-zenmoney

    • Clients with an mcpServers JSON file (Claude Desktop, Cursor, omp, …):

      "zenmoney": {
        "command": "npx",
        "args": ["-y", "mcp-server-zenmoney"],
        "env": { "ZENMONEY_TOKEN_FILE": "/home/<user>/.config/zenmoney-token" }
      }
  6. Tell the user to restart or reload MCP servers, then try: "Give me an overview of my finances."

🚀 Manual install

Requirements: Node.js >= 22.

  1. Get a token: open https://zerro.app/token, log in with your ZenMoney account and copy the token.

  2. Check it: ZENMONEY_TOKEN=... npx -y mcp-server-zenmoney --check prints OK: <login>, main currency …, N active accounts, M transactions (exit code 1 with the reason otherwise).

  3. Add it to your agent:

Claude Code

claude mcp add zenmoney -e ZENMONEY_TOKEN=YOUR_TOKEN -- npx -y mcp-server-zenmoney

Claude 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-token

Then 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 3000
  • MCP endpoint (Streamable HTTP): http://127.0.0.1:3000/mcp; GET /health returns {"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_HOST is refused unless MCP_HTTP_TOKEN is set. When set (on any bind), clients must send Authorization: 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

get_overview

Start here: today's date, main currency, net worth, account balances, this month's income/expenses, upcoming planned operations, data freshness

list_accounts

Accounts with balances (also in main currency), credit limits, bank and flags

list_categories

Category tree with kind (expense/income/both) and 12-month usage counts

list_payees

Known payees ranked by use, with last date and usual category

list_transactions

Filtered, paginated transaction search plus income/expense totals of all matches

summarize_transactions

Aggregate by category, parent category, payee, account or day/week/month/year; measure=both for cash flow

get_budget

Monthly budget vs. actual, remaining, % used and still-planned operations per category

list_planned

Planned / recurring operations still pending in a date range, with expected totals

list_debts

Per-person debt balances (positive = they owe you); optionally a person's debt transactions

suggest_category

Category/merchant suggestions for payee names from ZenMoney and your own history

sync

Pull changes from ZenMoney now; full=true re-downloads everything

Write (not registered in read-only mode):

Tool

Purpose

create_transactions

Record up to 50 expenses, incomes, transfers or debt operations; auto-categorizes, warns about duplicates

update_transactions

Edit amount, account, category, payee, comment, date, original amount; transfer destination. Type cannot change

delete_transactions

Soft-delete transactions by id

restore_transactions

Bring deleted transactions back (as copies with new ids)

create_category

Create a category or subcategory (one nesting level)

update_category

Rename, move, change kind, budget inclusion, mandatory flag, archive

delete_category

Delete a category, moving its transactions and planned operations to move_to or uncategorizing them

set_budgets

Set exact monthly budgets per category, total or uncategorized; 0 removes

create_account

Create a cash, card, checking or e-money account

update_account

Rename, archive, include/exclude from balance, savings flag, credit limit

adjust_account_balance

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

monthly_review

month (YYYY-MM)

Income, spending vs. previous month, budget status, large transactions, upcoming payments, suggestions

categorize_transactions

period

Proposes categories for uncategorized transactions, applies after confirmation (dry run first)

plan_budget

month (YYYY-MM)

Proposes budgets from the last three months and planned payments, applies with set_budgets after confirmation

🔒 Data, privacy and sync

  • The server keeps a local replica of your ZenMoney database, synced through the official API v8 (POST /v8/diff/, plus POST /v8/suggest/ for categories): a full download on first use, incremental diffs afterwards. Data older than ZENMONEY_SYNC_TTL seconds is refreshed automatically before a tool runs; sync forces it.

  • The replica is persisted to <cache dir>/snapshot-<hash>.json (directory created 0700, file 0600). 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. Set ZENMONEY_CACHE=off to keep everything in memory.

  • API origin: https://api.zenmoney.ru first; if it rejects the token before any request has succeeded, https://api.zenmoney.app is tried. ZENMONEY_API_URL pins 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's env if the agent host runs in a different zone.

  • Snapshots of tokens you no longer use stay in the cache directory; delete old snapshot-*.json files after rotating a token.

  • Logs go to stderr only.

Variable / flag

Default

Meaning

ZENMONEY_TOKEN

—

ZenMoney API token from https://zerro.app/token

ZENMONEY_TOKEN_FILE

—

File containing the token (used when ZENMONEY_TOKEN is empty; ~ expanded)

ZENMONEY_READ_ONLY / --read-only

false

1/true/yes/on registers only read tools

ZENMONEY_SYNC_TTL

30

Seconds before data is re-synced on the next tool call

ZENMONEY_CACHE_DIR

$XDG_CACHE_HOME/mcp-server-zenmoney, else ~/.cache/mcp-server-zenmoney

Snapshot cache directory

ZENMONEY_CACHE

on

0/false/no/off keeps data in memory only

ZENMONEY_API_URL

https://api.zenmoney.ru, fallback https://api.zenmoney.app

Pin a single API origin

MCP_TRANSPORT / --http

stdio

http serves Streamable HTTP

MCP_HTTP_HOST / --host

127.0.0.1

HTTP bind address

MCP_HTTP_PORT / --port

3000

HTTP port

MCP_HTTP_TOKEN

—

Bearer token HTTP clients must send; required for non-loopback binds

--check

—

Sync once with the configured token, print a one-line summary and exit

--help, -h / --version, -v

—

Print usage / version

CLI flags take precedence over the corresponding environment variables.

  • Amounts are always positive; type gives 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 are YYYY-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_to override 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_transactions follow 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_transactions category replaces the main category and keeps secondary tags; null leaves the transaction uncategorized. Moving a transaction to an account in another currency requires the new amount. Changing only amount of 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_transactions re-creates each transaction under a new id; restoring the same transaction again is a no-op that points at the existing copy.

  • Budgets: set_budgets sets an exact amount (lock on); 0 removes 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_balance records 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 build

Releases: 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 transports

  • src/config.ts — environment variables and CLI flags

  • src/server.ts — MCP server and agent instructions

  • src/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 tools
adjust_account_balanceReconcile account balanceA
Idempotent

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 categoryA
DestructiveIdempotent

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 transactionsA
DestructiveIdempotent

Delete transactions by id (soft delete; restore_transactions brings them back).

Inputs: ids (required), dry_run.

get_budgetMonthly budget statusB
Read-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 overviewA
Read-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 accountsA
Read-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 categoriesA
Read-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 personA
Read-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 payeesA
Read-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 operationsA
Read-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 transactionsA
Read-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 transactionsA
Idempotent

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 budgetsA
DestructiveIdempotent

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 payeesA
Read-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 reportA
Read-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 ZenMoneyA
Read-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 accountA
DestructiveIdempotent

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 categoryB
DestructiveIdempotent

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 transactionsA
DestructiveIdempotent

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

    A3.8/5.0

    Scored across 22 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI agents to interact with your Lunch Money personal finance data, providing tools for managing transactions, categories, budgets, assets, and accounts.
      15
      41 npm
      ISC
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables 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 npm
      MIT