ZenMoney MCP Server
You can audit, explore, and correct ZenMoney data through MCP, with previews before writes.
Sync ZenMoney history into a local cache, optionally refetching everything.
List categories with hierarchy and human-readable paths.
Find transactions by date, account, merchant, payee, MCC, uncategorized, or needs-review status.
Inspect merchant history with category counts, totals, and examples.
Review expenses and get ranked category candidates for uncategorized or suspicious transactions.
Apply category changes only after a dry-run preview and user confirmation.
Import Ozon Bank PDF statements with date + amount deduplication and dry-run preview.
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., "@ZenMoney MCP Server Review my expenses from last week and suggest category fixes"
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.
An MCP server for ZenMoney: it audits expenses, finds transactions with no category or a doubtful one, fixes categories and imports the missing transactions from an Ozon Bank PDF statement. Claude makes the call in the conversation, the server gives it the history and the candidates.
How it works
Claude ──MCP/stdio──▶ zen-money-mcp ──HTTPS──▶ ZenMoney API (diff v8)
│
▼
local cache in node:sqlite
the whole history, then only changesThe ZenMoney history is loaded into a local cache once, then only changes are pulled.
The server doesn't pick a category itself. From the history of the place (merchant, then payee, then MCC) it ranks candidates with a confidence, weighing recency, the day of week and the amount range. Claude picks.
Nothing is written without a confirmation: the writing tools default to a preview (
dryRun: true).
Related MCP server: local-budget
Tools
Tool | What it does |
| Pulls changes into the cache, |
| Categories with their hierarchy and paths, |
| Search by period, account, merchant, payee, MCC, uncategorized or doubtful |
| The whole category history of a place: counts, amounts, examples |
| Audit of a period: uncategorized or suspicious expenses with ranked candidates |
| Writes categories, shows "before → after" first |
| Imports an Ozon Bank PDF statement: duplicates by date and amount are skipped, new ones have no category |
A typical session: "Check my expenses for last week". Claude calls zen_sync and zen_review_expenses, suggests fixes, zen_apply_categories with dryRun: true shows the changes, and after your "yes" the same call with dryRun: false writes them.
Setup
Node 26 or newer: the cache lives in the built-in node:sqlite.
Register an OAuth app at developers.zenmoney.ru (or
.app) and get its consumer key and secret. Its redirect URI ishttp://localhost:53682/callback.Sign in once in a terminal:
ZEN_CLIENT_ID=… ZEN_CLIENT_SECRET=… npx -y @aimuzov/zen-money-mcp authA browser opens, and after sign-in the token is saved to the data directory. It refreshes itself afterwards.
Add the server to your MCP config, see .mcp.json.example:
{ "mcpServers": { "zen-money": { "command": "npx", "args": ["-y", "@aimuzov/zen-money-mcp"], "env": { "ZEN_CLIENT_ID": "your-consumer-key", "ZEN_CLIENT_SECRET": "your-consumer-secret", "ZEN_ENDPOINT": "ru" } } } }
Without a token the tools answer with a hint to run zen-money-mcp auth. There is no hosted connector: the server runs over stdio only and the data stays on your machine.
Commands
Usage: zen-money-mcp [serve|auth|sync [--full]|--help|--version]
serve run the MCP server over stdio (default)
auth sign in to ZenMoney in the browser and save the token
sync pull changes from ZenMoney into the local cache, --full refetches everythingEnvironment
Variable | Default | What it does |
| The OAuth app, needed to sign in and refresh | |
|
|
|
|
| Port of the |
| The full callback URI when the app has another one | |
|
| The |
|
|
|
| Error reports to Sentry, release |
They may also live in .env at the package root, the environment wins over the file.
Development
npm start # the server over stdio straight from src/
npm test # node --test
npm run typecheck
npm run lint
npm run format # oxlint --fix and prettier
npm run build # build/ for npmShared helpers and the CI steps come from infra-mcp-kit, formatting and lint rules from infra-site-kit. Times in the cache are Unix seconds, like in the API.
License
Available Tools
7 toolszen_apply_categoriesApply category changesA
Write category changes back to ZenMoney. ALWAYS call with dryRun:true first (the default) to preview before -> after, present that list to the user, and only call again with dryRun:false after the user explicitly confirms. tagId null clears the category.
Inputs: changes (required), dryRun.
zen_find_transactionsFind transactionsB
Flexible filtered transaction lookup (newest first). Filter by date range, account, merchant/payee/mcc, uncategorized-only, or needs-review-only.
Inputs: to, mcc, from, limit, +6 more.
zen_import_statementImport bank statementA
Import missing transactions from an Ozon-bank PDF statement into a ZenMoney account. Deduplicates against existing transactions by date + amount; credit repayments (transfers) are never created. ALWAYS call with dryRun:true first (the default) to preview the plan, present it to the user, and only call again with dryRun:false after explicit confirmation. New transactions are created without a category (run zen_review_expenses afterwards).
Inputs: account (required), filePath (required), dryRun.
zen_list_categoriesList categoriesB
The category (tag) vocabulary with hierarchy and human-readable paths. Use the ids when proposing category changes.
Inputs: kind.
zen_merchant_historyMerchant historyA
Full historical category breakdown for a place (by merchant id, payee text, or mcc): how often each category was used, totals, and recent examples. Use to dig deeper when a review row is ambiguous.
Inputs: to, mcc, from, payee, +1 more.
zen_review_expensesReview expensesA
Audit expenses in a date range: returns those that are uncategorized or likely mis-categorized, each with the current category and ranked candidate categories (with confidence) inferred from history at the same place. YOU decide the final category from this evidence, then propose changes via zen_apply_categories. Run zen_sync first if the cache may be stale.
Inputs: to (required), from (required), limit, account, +1 more.
zen_syncSync cacheA
Pull the latest data from ZenMoney into the local cache. Run this before auditing if the data may be stale. full:true re-fetches the entire history.
Inputs: full.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Core workflow tools (sync, review, apply, import) are clearly distinct, and descriptions explicitly chain them together. The only mild overlaps are zen_find_transactions with its needs-review/uncategorized filters versus zen_review_expenses, and zen_merchant_history versus the evidence already returned by review rows; descriptions largely disambiguate these.
All tools share a consistent zen_ prefix and mostly use verb_noun snake_case (review_expenses, apply_categories, import_statement, list_categories, find_transactions). Minor deviations: zen_sync is a bare verb, and zen_merchant_history is a noun phrase with no verb.
Seven tools is well within the ideal 3-15 range for a focused expense-categorization server. Each tool earns its place in the sync → review → evidence → apply loop, with no redundant entries.
The categorization lifecycle is well covered: cache refresh, filtered lookup, evidence gathering, category vocabulary, dry-run write-back, and statement import. Gaps exist beyond this scope — no account listing, no single-transaction create/edit/delete, and statement import is limited to Ozon-bank PDFs — but agents can work around them for the stated purpose.
Maintenance
Related MCP Connectors
Deterministic bank-statement parsing: messy CSV/OFX to clean categorized rows. In-memory only.
Import bank CSV exports, categorise transactions, total them by category or month, match expenses.
Import a bank CSV, categorise it, summarise it per currency and reconcile it against your expenses.
Import a bank CSV, categorise it, summarise it per currency and reconcile it against your expenses.
Related MCP Servers
- FlicenseBqualityCmaintenanceEnables read-only SQL queries and transaction classification tools for local expense tracking, including listing, filtering, and bulk account assignment with dry-run mode.8-
- AlicenseBqualityCmaintenanceEnables local-first personal finance management through deterministic tools for importing, categorizing, and analyzing bank transactions.36MIT
- AlicenseNot gradedqualityBmaintenanceEnables querying your own local bank and credit card statement files (CSV or PDF) in plain language, so you can discover forgotten recurring subscriptions, compare spending across months and quarters, and look up transactions without any bank logins or network calls.MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to analyze a local bank statement CSV through seven tools covering spending by category, top merchants, recurring subscriptions, unusual or duplicate charges, end-of-month forecasts, and transaction search, plus a monthly review prompt. CSV files stay on the user's machine, with only aggregated results and matched transactions exposed to the assistant.7MIT