# monter-mcp

Ask any MCP-capable assistant about your own money - locally, from the
export file you made in [Monter](https://monter.utilab.org).

```
"How much did I spend in July?"
"What do I pay for on autopilot every month?"
"How much does my credit card quietly cost me per month?"
"Is any of my cash sitting idle below market rate?"
```

Every answer is plain arithmetic over your own numbers. No server, no
account, no telemetry - this package reads one JSON file on your disk
and does math.

## Setup

1. In Monter on your iPhone: **Profile → Export your data (JSON)**, then
   AirDrop the file to your computer (e.g. into `~/Documents`).
2. Add the server to your assistant.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "monter": {
      "command": "npx",
      "args": ["-y", "monter-mcp", "--export", "/Users/you/Documents/monter-export-2026-08-21.json"]
    }
  }
}
```

**Claude Code**:

```bash
claude mcp add monter -- npx -y monter-mcp --export ~/Documents/monter-export-2026-08-21.json
```

Re-export any time; the server picks up the fresh file automatically
(it re-reads on change). Point the config at a stable path like
`~/Documents/monter-export.json` if you prefer renaming each export once.

## Tools

| Tool | What it answers |
|---|---|
| `snapshot_meta` | How fresh the export is and what it contains |
| `spending` | Total + per-category spending for a month or date range |
| `income` | Total income for a period |
| `transactions_search` | Find transactions by merchant or category |
| `subscriptions_overview` | Recurring costs normalised to monthly |
| `debts_overview` | Balances, APRs, and interest per month |
| `wallets_overview` | Balances per wallet and per currency |
| `idle_cash_check` | Cash above one month of expenses earning under 3% |
| `insurance_overview` | Premium total and its share of monthly expenses |
| `goals_overview` | Savings goals and progress |
| `checkins_stats` | Check-in streak and points |
| `health_score` | The app's 0-100 financial health score with components * |
| `money_leaks` | Detected leaks, their monthly cost, and resolved wins * |
| `freedom_day` | The Freedom Day estimate from the user's plan * |
| `profile_overview` | Stated setup: expenses, cushion target, income sources |
| `budgets_overview` | Budget limits vs actual spending |

\* Needs an export made from Monter 1.1+ (schemaVersion 2, with the
computed layer). Older exports still work for everything else.

## Privacy

Your export never leaves your machine through this package: the server
is local, makes no network calls, and contains no analytics of any
kind. One honest caveat: the assistant you connect it to is your
choice - anything it reads through these tools travels through that
assistant's provider under your agreement with them.

Figures are your own data, arithmetically rearranged. Nothing here is
financial advice.

## Development

```bash
npm install
npm test   # builds and runs smoke tests against test/fixture.json
```

MIT © MB Utilab