ZenMoney

💸 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_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.

🪄 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.

🤖 Agent setup guide (instructions for the AI agent doing the install)

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.

1. Verify the token:

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

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

1. 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).
2. 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, …): json "zenmoney": { "command": "npx", "args": ["-y", "mcp-server-zenmoney"], "env": { "ZENMONEY_TOKEN_FILE": "/home/ /.config/zenmoney-token" } }

1. 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: , 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 , 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):

Write (not registered in read-only mode):

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:

🔒 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 /snapshot- .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 ag