# 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:

```json
{
  "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

```env
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

```bash
npm install
cp .env.example .env
npm run dev
```

For a production-like local run from source:

```bash
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:

```json
{
  "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:

```json
{
  "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`.