ZenMoney MCP
The ZenMoney MCP server is primarily a read-only tool for syncing and analyzing ZenMoney financial data in-memory, with optional write capabilities if explicitly enabled.
Sync Management
sync_run: Trigger a full or incremental sync of the in-memory ZenMoney snapshotsync_status: Check the current cache and synchronization status
Accounts
accounts_list: List all accounts, with optional inclusion of archived ones
Transactions
transactions_list: List transactions with filters (date range, account, payee, tag, merchant, deleted status, limit)transactions_get: Retrieve a single transaction by IDtransactions_suggest: Get AI-based suggestions for transaction payee, merchant, or tags
Tags / Categories
tags_list: List all tags/categories, optionally including archived ones
Merchants
merchants_list: List merchants with optional text search and result limit
Budgets
budgets_list: List budgets filtered by month, tag, or userbudgets_get_status: Calculate category budget status (configured amount, actual spending, remaining, overspend) with optional child category inclusion
Optional Write Tools (require explicit opt-in via flag or env var)
Create, update, and delete: accounts, transactions, tags, merchants, reminders, and reminder markers
Update/delete operations require
expectedChangedfor conflict detection⚠️ Budget writes are not supported
The server does not persist financial data or API responses to disk, making it safe for read-heavy agentic workflows like financial analysis, reporting, and anomaly detection.
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 show my spending for the last month"
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.
ZenMoney MCP
Read-only MCP server for ZenMoney. It syncs ZenMoney data into process memory and exposes it through MCP tools and resources. It does not persist financial data or API responses to disk.
Agentic Workflows
The read-only mode is a good fit for agentic workflows with tools such as Hermes and OpenClaw. Agents can analyze transactions in the way the user asks, compare spending patterns, prepare recurring personal-finance reports, and surface anomalies without being able to create, update, or delete ZenMoney data.
Related MCP server: mcp-beancount
Unofficial Project
This is an unofficial project and is not affiliated with, endorsed by, or sponsored by ZenMoney. Users are responsible for complying with ZenMoney terms and for protecting their own access tokens.
MCP Client Config
Use the published CLI through npx and pass runtime configuration through your MCP client:
{
"mcpServers": {
"zenmoney": {
"command": "npx",
"args": ["-y", "@nonnname/zenmoney-mcp"],
"env": {
"ZENMONEY_ACCESS_TOKEN": "paste-token-here",
"ZENMONEY_SYNC_ON_START": "true",
"ZENMONEY_API_BASE_URL": "https://api.zenmoney.ru/v8",
"ZENMONEY_DEFAULT_RESULT_LIMIT": "100",
"ZENMONEY_MAX_RESULT_LIMIT": "500",
"ZENMONEY_REQUEST_TIMEOUT_MS": "30000",
"ZENMONEY_ENABLE_WRITE_TOOLS": "false"
}
}
}
}The same example is available in mcp-config.example.json.
Configuration
ZENMONEY_ACCESS_TOKEN=
ZENMONEY_SYNC_ON_START=true
ZENMONEY_API_BASE_URL=https://api.zenmoney.ru/v8
ZENMONEY_DEFAULT_RESULT_LIMIT=100
ZENMONEY_MAX_RESULT_LIMIT=500
ZENMONEY_REQUEST_TIMEOUT_MS=30000
ZENMONEY_ENABLE_WRITE_TOOLS=falseZENMONEY_DEFAULT_RESULT_LIMIT and ZENMONEY_MAX_RESULT_LIMIT limit MCP responses from the in-memory snapshot. They do not limit ZenMoney API synchronization.
Local Development
npm install
cp .env.example .env
npm run devFor a production-like local run from source:
npm run build
npm startTools
sync_runsync_statusaccounts_listtransactions_listtransactions_gettransactions_suggesttags_listmerchants_listbudgets_listbudgets_get_status
budgets_get_status calculates read-only category budget status for a month. It reports the configured outcome budget, actual spending, remaining amount, overspend state, and matched category ids. Child categories are included by default with includeChildren: true.
Optional Write Tools
The server is read-only by default. Write tools are not registered unless you explicitly enable them at process startup.
Enable write tools with a launch argument:
{
"mcpServers": {
"zenmoney": {
"command": "npx",
"args": ["-y", "@nonnname/zenmoney-mcp", "--enable-write-tools"],
"env": {
"ZENMONEY_ACCESS_TOKEN": "paste-token-here"
}
}
}
}Or enable write tools with an environment variable:
{
"env": {
"ZENMONEY_ACCESS_TOKEN": "paste-token-here",
"ZENMONEY_ENABLE_WRITE_TOOLS": "true"
}
}Write tools can create, update, and delete ZenMoney user entities except budgets. Update and delete tools require expectedChanged, which is the changed value returned by the read tools. If the entity changes remotely before the write, the server returns a conflict and does not send the mutation.
Budget writes are not supported.
Write tools registered only after opt-in:
accounts_createaccounts_updateaccounts_deletetransactions_createtransactions_create_expensetransactions_create_incometransactions_create_transfertransactions_updatetransactions_deletetags_createtags_updatetags_deletemerchants_createmerchants_updatemerchants_deletereminders_createreminders_updatereminders_deletereminder_markers_createreminder_markers_updatereminder_markers_delete
Resources
zenmoney://statuszenmoney://accountszenmoney://transactionszenmoney://transactions/{id}zenmoney://tagszenmoney://merchantszenmoney://budgetszenmoney://schema/accountzenmoney://schema/transactionzenmoney://schema/tagzenmoney://schema/merchantzenmoney://schema/budget
Contributor setup, verification, and maintainer release instructions live in CONTRIBUTING.md.
Available Tools
10 toolsaccounts_listZenMoney AccountsC
List accounts from the in-memory ZenMoney snapshot.
Inputs: includeArchived.
budgets_get_statusZenMoney Budget StatusB
Calculate read-only spending and remaining amount for a category budget.
Inputs: month (required), tagId (required), includeChildren, userId.
budgets_listZenMoney BudgetsC
List budgets from the in-memory ZenMoney snapshot.
Inputs: month, tagId, userId.
merchants_listZenMoney MerchantsC
List merchants from the in-memory ZenMoney snapshot.
Inputs: query, limit.
sync_runZenMoney SyncC
Synchronize the in-memory ZenMoney snapshot.
Inputs: full.
sync_statusZenMoney Cache StatusA
Return memory cache initialization and synchronization status.
Inputs: no named parameters.
tags_listZenMoney TagsC
List tags/categories from the in-memory ZenMoney snapshot.
Inputs: includeArchived.
transactions_getZenMoney TransactionB
Get one transaction by id from the in-memory ZenMoney snapshot.
Inputs: id (required).
transactions_listZenMoney TransactionsC
List transactions from the in-memory ZenMoney snapshot.
Inputs: dateFrom, dateTo, accountId, tagId, +4 more.
transactions_suggestZenMoney Suggest TransactionC
Ask ZenMoney to suggest transaction payee, merchant, or tags.
Inputs: payee, merchant, amount, accountId, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Each tool targets a distinct entity or operation: listing for accounts, budgets, merchants, tags, and transactions; plus specific operations like get, suggest, sync, and status. No overlapping purposes.
All tools follow a consistent 'entity_verb' pattern (e.g., accounts_list, sync_run). While the order differs from the typical 'verb_noun', the pattern is uniform across the entire set.
With 10 tools, the server covers core operations for a read-only snapshot viewer: listing all entities, specific retrieval, suggestion, and synchronization management. This is well-scoped.
The tool set provides list operations for all major entities and a get for transactions, but lacks individual get endpoints for accounts, budgets, merchants, and tags. This leaves gaps for detailed inspection.
Maintenance
Related MCP Connectors
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Query your real net worth, spending, transactions, budgets and portfolio from any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceProvides an MCP server for querying and managing Monarch Money personal finance data through a local SQLite mirror with read-only SQL access. It enables users to sync transaction history from the Monarch API and analyze accounts, categories, and tags.1MIT
- FlicenseNot gradedqualityCmaintenanceA read-only MCP server that gives AI agents structured access to a Beancount personal finance ledger.1-
- AlicenseAqualityDmaintenanceMCP server for ZenMoney that enables AI clients to read and manage personal finance data (accounts, categories, transactions, etc.) via natural language.1786 npmMIT
- AlicenseAqualityDmaintenanceAn MCP server for the Zenmoney personal-finance API that exposes read access to accounts, transactions, categories, budgets, merchants, and reminders, plus the ability to create transactions.8MIT