ZenMoney MCP Server

A read-only Model Context Protocol (MCP) server for the ZenMoney personal finance service. Provides AI assistants with access to your financial data: accounts, transactions, budgets, categories, and more.

Features

Accounts — balances, credit limits, account types (cards, cash, loans, deposits)
Transactions — full history with filtering by date, account, and category
Budgets — monthly spending limits by category
Tags — hierarchical transaction categories
Merchants — payees and payers
Reminders — recurring transaction templates and planned instances
Currencies — all instruments with exchange rates
Caching — data is fetched once and served from memory; refresh on demand
ID resolution — raw IDs are resolved to human-readable names (account titles, currency codes, tag names, merchant names)

Getting a Token

This server requires a ZenMoney OAuth2 access token. You can obtain one from Zerro.app:

Open Zerro.app and log in with your ZenMoney account
Open browser DevTools (F12) → Application → Local Storage
Find the token key and copy its value

Alternatively, register your own OAuth2 application via the ZenMoney API.

Quick Start

No installation required — run directly with npx:

ZENMONEY_TOKEN=your-token npx -y @roher/zenmoney-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "zenmoney": {
      "command": "npx",
      "args": ["-y", "@roher/zenmoney-mcp"],
      "env": {
        "ZENMONEY_TOKEN": "your-token-here"
      }
    }
  }
}

Claude Code

Add to ~/.claude/settings.json under mcpServers:

{
  "zenmoney": {
    "command": "npx",
    "args": ["-y", "@roher/zenmoney-mcp"],
    "env": {
      "ZENMONEY_TOKEN": "your-token-here"
    }
  }
}

Then run /mcp in Claude Code to reconnect MCP servers.

VS Code

Add to your .vscode/mcp.json:

{
  "servers": {
    "zenmoney": {
      "command": "npx",
      "args": ["-y", "@roher/zenmoney-mcp"],
      "env": {
        "ZENMONEY_TOKEN": "your-token-here"
      }
    }
  }
}

Building from Source

git clone https://github.com/roher-roher/zenmoney-mcp.git
cd zenmoney-mcp
npm install
npm run build

Then use node /path/to/zenmoney-mcp/build/index.js instead of npx in the configurations above.

Tools

Tool	Description	Parameters
`get_accounts`	List all accounts with balances	`include_archived?`
`get_transactions`	Get transactions with filtering and pagination	`date_from?`, `date_to?`, `account_id?`, `tag_id?`, `include_deleted?`, `limit?`, `offset?`
`get_tags`	List all categories/tags with hierarchy	—
`get_merchants`	List all merchants	—
`get_instruments`	List currencies with exchange rates	—
`get_budgets`	Get monthly budget entries	`date?`, `tag_id?`
`get_reminders`	List recurring transaction templates	—
`get_reminder_markers`	Get planned transaction instances	`state?`, `date_from?`, `date_to?`
`get_user`	Get user information	—
`refresh_data`	Invalidate cache and re-fetch from API	—

Tool Details

get_accounts

Returns all user accounts (bank cards, cash, loans, deposits, e-wallets, debt trackers) with current balances and currency codes.

get_transactions

Returns transactions sorted by date (newest first). Supports filtering:

date_from / date_to — date range in yyyy-MM-dd format
account_id — filter by income or outcome account UUID
tag_id — filter by category UUID
include_deleted — include soft-deleted transactions (default: false)
limit / offset — pagination (default: 1000 / 0)

Response includes total count for pagination.

get_budgets

Returns budget entries (monthly spending/income limits per category). Filter by:

date — month start date in yyyy-MM-dd format (e.g. 2025-01-01)
tag_id — specific category UUID

get_reminder_markers

Returns planned transaction instances generated from reminders. Filter by:

state — planned, processed, or deleted
date_from / date_to — date range in yyyy-MM-dd format

How It Works

The server uses the ZenMoney /v8/diff/ API endpoint — the only read mechanism available.

Caching and sync:

First run — performs a full sync (serverTimestamp: 0) and saves the result to disk at ~/.zenmoney-mcp/cache.json
Subsequent runs — loads cached data from disk and fetches only changes since the last sync (incremental diff), which is significantly faster
Within a session — all tool calls are served from in-memory cache with no additional API requests
refresh_data — clears both disk and in-memory cache; the next tool call will perform a full sync

ID resolution: all internal IDs are automatically resolved to human-readable values — account names, currency codes (e.g. RUB, USD), tag titles, and merchant names.

License

MIT

@roher/zenmoney-mcp

Quick Install