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.

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=false

ZENMONEY_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 dev

For a production-like local run from source:

npm run build
npm start

Tools

• sync_run
• sync_status
• accounts_list
• transactions_list
• transactions_get
• transactions_suggest
• tags_list
• merchants_list
• budgets_list
• budgets_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_create
• accounts_update
• accounts_delete
• transactions_create
• transactions_create_expense
• transactions_create_income
• transactions_create_transfer
• transactions_update
• transactions_delete
• tags_create
• tags_update
• tags_delete
• merchants_create
• merchants_update
• merchants_delete
• reminders_create
• reminders_update
• reminders_delete
• reminder_markers_create
• reminder_markers_update
• reminder_markers_delete

Resources

• zenmoney://status
• zenmoney://accounts
• zenmoney://transactions
• zenmoney://transactions/{id}
• zenmoney://tags
• zenmoney://merchants
• zenmoney://budgets
• zenmoney://schema/account
• zenmoney://schema/transaction
• zenmoney://schema/tag
• zenmoney://schema/merchant
• zenmoney://schema/budget

Contributor setup, verification, and maintainer release instructions live in CONTRIBUTING.md.