# zenmoney-mcp

MCP server for [ZenMoney](https://zenmoney.ru) — access your personal finance data from any MCP-compatible AI client (Claude Desktop, Cursor, etc.).

## Features

| Tool | Description |
|------|-------------|
| `sync_data` | Sync data with ZenMoney (run first) |
| `list_accounts` | List wallets, cards, and cash accounts |
| `list_categories` | List expense/income categories with hierarchy |
| `list_merchants` | List known merchants/payees |
| `list_transactions` | List and filter recent transactions |
| `add_expense` | Add an expense transaction |
| `add_income` | Add an income transaction |
| `add_transfer` | Transfer money between accounts (including cross-currency) |
| `suggest_category` | Get auto-suggested category for a payee |
| `review_transactions` | Find likely duplicates, uncategorized entries, and unusually large transactions |
| `change_transaction_category` | Replace the category of an existing transaction |
| `update_transaction_details` | Update a transaction's payee/payer or comment |
| `delete_transaction` | Delete an existing transaction |
| `create_category` | Create an income, expense, or combined category |
| `update_category` | Rename a category or change its hierarchy and budget settings |
| `delete_category` | Delete an unused leaf category |
| `merge_categories` | Move transactions into another category and remove the source category |

All tools that modify ZenMoney advertise MCP write/destructive annotations so compatible clients can request approval before executing them. Approval behavior still depends on the MCP client's policy and configuration.

## Prerequisites

- Node.js >= 18
- A [ZenMoney](https://zenmoney.ru) account
- API token from [zerro.app/token](https://zerro.app/token)

## Quick start

No cloning or building needed — just add to your MCP client config:

### Claude Desktop

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "zenmoney": {
      "command": "npx",
      "args": ["-y", "zenmoney-mcp"],
      "env": {
        "ZENMONEY_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "zenmoney": {
      "command": "npx",
      "args": ["-y", "zenmoney-mcp"],
      "env": {
        "ZENMONEY_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add zenmoney -- npx -y zenmoney-mcp
```

Replace `your_token_here` with your token from [zerro.app/token](https://zerro.app/token).

### Claude Desktop (MCPB bundle)

If you prefer a one-click install without editing JSON, build a `.mcpb` bundle and drag it into Claude Desktop → Settings → Extensions:

```bash
npm install
npm run pack:mcpb
# → dist/zenmoney-mcp-<version>.mcpb
```

On install, Claude Desktop will prompt for your ZenMoney token (stored in the OS keychain).

### From source

```bash
git clone https://github.com/a-tarasoff/zenmoney-mcp.git
cd zenmoney-mcp
npm install
npm run build
cp .env.example .env  # add your token
```

## Usage

Once configured, start a conversation and ask your AI client to:

1. **Sync first** — "Sync my ZenMoney data"
2. **Browse** — "Show me my accounts", "List my categories"
3. **Query** — "Show expenses for the last 7 days", "List transactions from January 1–31", "How much did I spend on groceries?"
4. **Add transactions** — "Add a 500 RUB expense for coffee today"
5. **Transfer** — "Transfer 1000 USD from Checking to Euro Card, received 920 EUR"
6. **Review** — "Review July for duplicate, uncategorized, and unusually large transactions"
7. **Organize categories** — "Create an expense category named Utilities under Housing"
8. **Clean up** — "Change this transaction to Groceries" or "Merge Dining Out into Food"

Transaction listing and review tools return transaction IDs. Use those IDs for precise edits instead of relying on ambiguous dates, amounts, or payee names.

## Contributing

PRs welcome! Feel free to open issues for bugs or feature requests.

## License

[MIT](LICENSE)