# monarch-mcp-ultimate

The most capable Monarch Money MCP server — merging the best features from all known implementations into one clean TypeScript project.

## Features

- **Cookie-based auth** for Apple Sign In / passkey / Google users (no email+password needed)
- **Standard email+password auth** as a fallback
- **47 tools** covering reads, writes, rules CRUD, merchant management, and intelligence analysis
- **Natural language dates** — "last month", "30 days ago", "this year", etc.
- **Compact token-efficient transaction format** by default (verbose mode available)
- **Full transaction rules CRUD** — get, create, update, delete with exact GraphQL from Monarch's web app
- **Intelligence tools** — rule candidates, uncategorized summary, categorization suggestions from history

---

## Authentication

### Option A — Cookie Auth (for Apple Sign In / passkey / Google users)

This is the only option if you log in with Apple or Google or a passkey.

1. Open [app.monarch.com](https://app.monarch.com) in Chrome/Safari
2. Open DevTools → **Application** tab → **Cookies** → `app.monarch.com`
3. Copy the value of `session_id`
4. Copy the value of `csrftoken`

```json
{
  "env": {
    "MONARCH_SESSION_ID": "your-session-id-here",
    "MONARCH_CSRF_TOKEN": "your-csrftoken-here"
  }
}
```

> Sessions expire — you'll need to update these when Monarch logs you out (typically every 30 days or on password change).

### Option B — Token Auth (email+password users)

Run the login helper to get a token:

```bash
cd /Users/kevinreed/Dev/monarch-mcp-ultimate
node -e "
const { login } = require('./dist/auth');
login('your@email.com', 'yourpassword').then(r => console.log('Token:', r.token));
"
```

Then set `MONARCH_TOKEN` in your Claude Desktop config.

---

## Claude Desktop Config

### Cookie auth (`~/.config/claude/claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "monarch": {
      "command": "node",
      "args": ["/Users/kevinreed/Dev/monarch-mcp-ultimate/dist/index.js"],
      "env": {
        "MONARCH_SESSION_ID": "abc123...",
        "MONARCH_CSRF_TOKEN": "xyz789..."
      }
    }
  }
}
```

### Token auth

```json
{
  "mcpServers": {
    "monarch": {
      "command": "node",
      "args": ["/Users/kevinreed/Dev/monarch-mcp-ultimate/dist/index.js"],
      "env": {
        "MONARCH_TOKEN": "your-token-here"
      }
    }
  }
}
```

---

## All 47 Tools

### Read Tools (21)

| Tool | Description |
|------|-------------|
| `get_accounts` | All accounts; verbosity: compact/full |
| `get_account_balance` | Balance for a specific account |
| `get_transactions` | Paginated transactions with natural language dates |
| `get_transactions_needing_review` | Transactions flagged for review |
| `search_transactions` | Keyword/merchant search |
| `get_spending_by_category` | Spending totals per category |
| `get_spending_summary` | Multi-axis: by category, group, merchant + totals |
| `get_complete_financial_overview` | 5 parallel API calls — one-shot snapshot |
| `get_budget_summary` | Planned vs actual by category |
| `get_cashflow` | Income + expenses + savings for a date range |
| `get_net_worth` | Total assets minus liabilities |
| `get_monthly_summary` | Income/expenses/savings for a month |
| `get_categories` | All categories and groups |
| `get_account_snapshots` | Historical balance snapshots |
| `get_portfolio` | Investment holdings and performance |
| `get_tags` | All transaction tags |
| `get_recurring_transactions` | Subscriptions, bills, recurring income |
| `get_transaction_rules` | All auto-categorization rules |
| `get_goals` | Savings goals |
| `get_institutions` | Connected institutions and credential status |
| `get_merchant` | Merchant details and recurring stream config |

### Transaction Write Tools (7)

| Tool | Description |
|------|-------------|
| `update_transaction` | Category, merchant, amount, date, notes, flags |
| `mark_transaction_reviewed` | Mark one or many as reviewed |
| `create_transaction` | Create a new manual transaction |
| `delete_transaction` | Delete by ID |
| `set_transaction_tags` | Set tags (replaces existing) |
| `split_transaction` | Split into multiple parts |
| `bulk_update_transactions` | Parallel updates with dry_run support |

### Category / Tag Write Tools (3)

| Tool | Description |
|------|-------------|
| `create_category` | New category in a group |
| `delete_category` | Delete, optionally moving transactions |
| `create_tag` | New transaction tag |

### Account Write Tools (4)

| Tool | Description |
|------|-------------|
| `update_account` | Rename, toggle net worth, hide |
| `delete_account` | Delete account |
| `create_manual_account` | Create manual account |
| `refresh_accounts` | Trigger data refresh |

### Budget Tools (1)

| Tool | Description |
|------|-------------|
| `set_budget_amount` | Set monthly budget for category or group |

### Rules + Merchant Tools (4)

| Tool | Description |
|------|-------------|
| `create_transaction_rule` | Merchant pattern → category + optional tag/hide actions |
| `update_transaction_rule` | Update existing rule |
| `delete_transaction_rule` | Delete rule by ID |
| `update_merchant` | Rename merchant or configure recurring stream |

### Intelligence Tools (3)

| Tool | Description |
|------|-------------|
| `get_rule_candidates` | Suggests rules for merchants with consistent category history |
| `get_uncategorized_summary` | Counts uncategorized + needs-review by month |
| `get_categorization_suggestions` | Suggests categories for uncategorized transactions based on history |

---

## Natural Language Dates

All date fields accept plain English:

| Input | Resolves to |
|-------|-------------|
| `today` | Today's date |
| `yesterday` | Yesterday |
| `this month` | First of current month |
| `last month` | First of previous month |
| `this year` | Jan 1 of current year |
| `last year` | Jan 1 of previous year |
| `30 days ago` | 30 days before today |
| `6 months ago` | 6 months before today |
| `1 year ago` | 1 year before today |
| `2025-03-15` | Passed through as-is |

---

## Example Prompts

```
"Show me everything I spent on restaurants last month"
→ get_transactions(start_date="last month", end_date="today", category_id=...)

"What's my financial overview?"
→ get_complete_financial_overview()

"How much have I spent in the last 90 days, broken down by category?"
→ get_spending_summary(start_date="90 days ago", end_date="today")

"Find rules I should be creating based on my spending patterns"
→ get_rule_candidates(lookback_days=90, min_confidence=0.8)

"Which uncategorized transactions from last month can be auto-categorized?"
→ get_categorization_suggestions(lookback_days=30)

"Create a rule: anything from Amazon goes to Shopping"
→ create_transaction_rule(merchant_criteria_value="Amazon", merchant_criteria_operator="contains", set_category_id="...")

"Rename the merchant 'AMZN MKTP US' to 'Amazon'"
→ update_merchant(merchant_id="...", name="Amazon")

"Mark all transactions needing review as reviewed"
→ get_transactions_needing_review() → mark_transaction_reviewed(transaction_ids=[...])

"What's my uncategorized backlog for the past 6 months?"
→ get_uncategorized_summary(lookback_months=6)
```

---

## Build

```bash
cd /Users/kevinreed/Dev/monarch-mcp-ultimate
npm install
npm run build
```

## Sources

Built by merging:
- **keithah/monarch-mcp** — TypeScript base, Smithery support
- **jamiew/monarch-mcp** — Natural language dates, compact format, tool annotations, auth retry
- **robcerda/monarch-mcp-server** — Full rules CRUD GraphQL, merchant management, split transactions
- **randallt21/monarch** — Intelligence engine: rule candidates, auto-categorization logic