MAX MCP

Pull credit card expenses from MAX (Israel), categorize them, and hand the result to a Claude agent that analyzes spending behaviour against current Israeli market conditions.

MAX has no public API, so transactions are collected by driving a headless browser session against max.co.il using israeli-bank-scrapers.

Pieces

Start here: run.py is the interface. Edit the configuration block at the top of that file, then python3 run.py. Everything else is machinery.

Data flow: max.co.il → scraper → framework.categorize_all → data/expenses.json → analyst_agent.py → data/analysis.md

Related MCP server: Monarch Money MCP Server

Setup

pip install -r requirements.txt
(cd scraper && npm install)      # downloads Chromium, ~300MB
cp .env.example .env             # then fill in MAX_USERNAME, MAX_PASSWORD, ANTHROPIC_API_KEY

Running it

python3 run.py

Open run.py, change the settings in the CONFIGURATION block, save, run again. Every setting has EXAMPLE lines above it showing the forms it accepts; the examples are commented out, so only the uncommented line takes effect.

The settings, in short:

Typical loop: run once with FETCH = True to download, then set it to False and re-run freely while you change dates and cards — no repeated logins.

Run it with CARDS = [] first: the card table it prints shows every name you can put in CARDS.

Running the MCP server

Register it with your MCP client (Claude Desktop, Claude Code, etc.):

{
  "mcpServers": {
    "max-expenses": {
      "command": "python",
      "args": ["/Users/erezcohen/Documents/MAX MCP/MAX_mcp.py"]
    }
  }
}

Tools it exposes:

• fetch_expenses(months_back, show_browser, timeout_seconds) — log in, scrape every card on the account, categorize, cache. Takes 30–120 seconds. Pass show_browser=true the first time to watch the login.

• get_expenses(start_date, end_date, category, min_amount, card, refunds_only, limit) — read the cache.

• get_spending_summary(start_date, end_date, card) — totals per category, per budget nature, per card, per month, plus top merchants. The agent's input.

• list_cards() — the cards found, with spend and date range per card.

• list_categories() — the framework itself.

• recategorize(merchant_pattern, category) — permanently map a merchant to a category, overriding the keyword classifier. Use it to clear out uncategorized.

Multiple cards

One MAX login covers every card on the account. The scraper returns each card separately, so every transaction carries card (the number MAX reports) and card_label. Nothing needs configuring for this to work — it is the default.

To get readable names instead of card numbers, set MAX_CARD_LABELS in .env to one line of JSON. Keys match against the end of the card number, so the last four digits are enough and the full number never has to be stored:

MAX_CARD_LABELS={"1234": "personal", "5678": "business", "9012": "spouse"}

Anywhere a card argument appears, either the label or the trailing digits work. get_spending_summary without a card returns the household total plus a by_card breakdown (each card's own category and nature mix) and by_month_by_card, so a rising total can be traced to the card causing it.

The agent gets one extra thing from having several cards: a merchants_on_multiple_cards list. The same subscription billed to two cards is invisible in a household total and is the most common duplicate charge.

Running the analyst

python analyst_agent.py                 # last 3 months, all cards, with market research
python analyst_agent.py --months 6
python analyst_agent.py --card personal # scope to one card
python analyst_agent.py --no-research   # numbers only, no web search

Writes data/analysis.md.

Signs: charges vs refunds

MAX reports a purchase as a negative amount and a refund or credit as a positive one, and that sign is preserved end to end — amount in the cache is exactly what MAX said, plus an is_refund convenience flag.

Every total is net: spending minus refunds, so a refund reduces the category and card it landed in instead of inflating them. gross_spend and refunds are reported alongside the net figure at the top level, per card, and per category, because a category that looks cheap only because one large refund landed in it is a different story from one that was genuinely low-spend.

framework.cost_of(txn) is the single place that flips the sign into "money that left the account" terms. Use it rather than touching amount directly — and never abs() an amount, which is what turns a ₪4,000 refund into ₪4,000 of spending.

get_expenses(refunds_only=True) lists just the money that came back. min_amount filters on magnitude, so it surfaces large refunds as well as large charges.

The categorization framework

Each category in framework.py carries a nature — fixed, variable, discretionary, or investment — because the analysis reasons very differently about rent than about restaurants. Classification is deterministic keyword matching against the merchant name in Hebrew or English, longest keyword first. Anything unmatched lands in uncategorized, and the summary reports what share of spend that is, since a high uncategorized share undermines every conclusion drawn from the totals. Fix those with recategorize.

To add a category, append a Category(...) to CATEGORIES. To improve an existing one, add keywords to its tuple.

Notes

• Credentials live only in .env and are passed to the Node subprocess through its environment, never on the command line.

• data/ and .env are gitignored. The cache contains your full transaction history — treat it as you would a bank statement.

• MAX occasionally changes its login flow, which breaks the scraper. When that happens, update israeli-bank-scrapers (cd scraper && npm update) before debugging anything else.