Skip to main content
Glama
ZenMoney MCP Server

ZenMoney MCP Server

by aimuzov

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 changes
  • The 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

zen_sync

Pulls changes into the cache, full: true refetches the whole history

zen_list_categories

Categories with their hierarchy and paths, kind: expenses, income or all

zen_find_transactions

Search by period, account, merchant, payee, MCC, uncategorized or doubtful

zen_merchant_history

The whole category history of a place: counts, amounts, examples

zen_review_expenses

Audit of a period: uncategorized or suspicious expenses with ranked candidates

zen_apply_categories

Writes categories, shows "before → after" first

zen_import_statement

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.

  1. Register an OAuth app at developers.zenmoney.ru (or .app) and get its consumer key and secret. Its redirect URI is http://localhost:53682/callback.

  2. Sign in once in a terminal:

    ZEN_CLIENT_ID=… ZEN_CLIENT_SECRET=… npx -y @aimuzov/zen-money-mcp auth

    A browser opens, and after sign-in the token is saved to the data directory. It refreshes itself afterwards.

  3. 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 everything

Environment

Variable

Default

What it does

ZEN_CLIENT_ID, ZEN_CLIENT_SECRET

The OAuth app, needed to sign in and refresh

ZEN_ENDPOINT

ru

ru is api.zenmoney.ru, app is api.zenmoney.app

ZEN_REDIRECT_PORT

53682

Port of the http://localhost:<port>/callback

ZEN_REDIRECT_URI

The full callback URI when the app has another one

ZEN_DATA_DIR

~/.config/zen-money-mcp

The cache.sqlite cache and the auth.json token

LOG_LEVEL

info

error, warn, info or debug

SENTRY_DSN

Error reports to Sentry, release zen-money-mcp@<version>

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 npm

Shared 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

MIT

Available Tools

7 tools
zen_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

    A3.9/5.0

    Scored across 7 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      C
      maintenance
      Enables read-only SQL queries and transaction classification tools for local expense tracking, including listing, filtering, and bulk account assignment with dry-run mode.
      8
      -
    • A
      license
      B
      quality
      C
      maintenance
      Enables local-first personal finance management through deterministic tools for importing, categorizing, and analyzing bank transactions.
      36
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      7
      MIT