Monarch Money MCP Server

MCP server for Monarch Money — a personal finance app that aggregates accounts, transactions, budgets, and net worth across institutions. This server gives an AI assistant read and write access to the same data the Monarch web/mobile app shows you, scoped to your own account.

Highlights

• 23 consolidated tools across two groups (readonly, manage) covering accounts, balances, net worth, cashflow, transactions, categories, tags, transaction rules, and budgets
• Encrypted on-disk session at ~/.monarch-money-mcp/session.enc — the server never accepts a Monarch password through a tool input
• Tool group filtering via env vars — run the server in a strict read-only mode, or hand-pick the exact tools you want exposed to the agent
• Custom thin GraphQL transport targeting api.monarch.com/graphql — no third-party Monarch client dependency

Why a custom GraphQL client?

The tools in this server span accounts, transactions, budgets, rules, categories, and net worth. We evaluated existing TypeScript Monarch clients and didn't find one that covered the surface we needed and was actively maintained. Rather than wrap a partial third-party client and patch around its gaps, this server ships a small in-house transport (shared/src/monarch-client/graphql-transport.ts) that is deliberately minimal: build the request, surface auth/network errors with typed exceptions, return the typed data payload. Operations live as named GraphQL strings in shared/src/monarch-client/operations.ts so the surface is grep-able and easy to extend.

Authentication

Monarch's /auth/login/ endpoint gates first-time logins from an unfamiliar device behind an email OTP Monarch sends to your inbox, plus per-IP throttling and a Cloudflare bot challenge. That makes a fully unattended email + password flow impossible on a fresh install — the user has to read the code from email at least once. After that one-time pairing, the same install can log in with credentials alone.

Because of that, the recommended path is to paste a session token rather than ship credentials in the env. The server supports four ways to authenticate, in priority order:

1. Env-var session token (recommended)

Paste a token once into the launcher's environment. Headless, autonomous, no OTP gate.

MONARCH_SESSION_TOKEN=<your-token>

Where to get a token:

• Run npm run login (option 3) once and copy it out of ~/.monarch-money-mcp/session.enc (after decrypting), OR
• Open the Monarch web app DevTools → Network → any /graphql request → copy the value of the Authorization: Token <…> header.

The token is resolved at startup, validated, and persisted to disk so the env var becomes optional after the first run.

2. Tool-based token paste

If you can't set env vars (e.g., a UI that doesn't expose the launcher's env), call the monarch_login_with_token tool with the token as input. The server validates it via Monarch's me endpoint before saving.

3. Env-var email + password (best-effort)

Set credentials in the env and let the server log in:

MONARCH_EMAIL=<email>
MONARCH_PASSWORD=<password>
MONARCH_TOTP=<code>          # only if your account has 2FA enabled
MONARCH_EMAIL_OTP=<code>     # only on the first launch from a new install

On the first launch from a fresh install Monarch sends an OTP to your email. The server logs a clear stderr message explaining what to do; set MONARCH_EMAIL_OTP=<code> and restart. Subsequent launches reuse the persisted device-uuid and skip the OTP gate.

4. Interactive CLI

cd servers/monarch-money/local
npm run login

Prompts for email, password, optional TOTP, and (if challenged) the email OTP. Writes the encrypted token to ~/.monarch-money-mcp/session.enc.

Session encryption

The token is encrypted at rest with AES-256-GCM. The encryption key is derived via scrypt from a passphrase:

• If MONARCH_SESSION_PASSPHRASE is set, that's the passphrase.
• Otherwise, the passphrase is derived from the machine's hostname (os.hostname()) and the current user (os.userInfo().username) — making the encrypted file machine-bound by default.

This isn't a defense against a local attacker who already controls your shell, but it does prevent accidental cross-host disclosure (e.g., the file ending up in a backup that gets restored on another machine).

Tool Groups

Tools are tagged with one or more groups. The default exposes everything; setting MONARCH_ENABLED_TOOL_GROUPS (or MONARCH_ENABLED_TOOLS / MONARCH_DISABLED_TOOLS) narrows the surface.

| Group | Includes | | ---------- | -------------------------------------------------------------------------------------------------------------------- | | readonly | Lookups only — accounts, transactions, balances, net worth, categories, budgets, rules. | | manage | Everything in readonly plus mutations — create/update/delete transactions, tags, rules, budgets; refresh accounts. |

Filter precedence: MONARCH_ENABLED_TOOLS (whitelist, exact names) > MONARCH_ENABLED_TOOL_GROUPS (group filter) > MONARCH_DISABLED_TOOLS (blacklist, exact names).

# Strict read-only deployment
MONARCH_ENABLED_TOOL_GROUPS=readonly

# Deny one specific tool
MONARCH_DISABLED_TOOLS=delete_transaction

# Whitelist exactly two tools
MONARCH_ENABLED_TOOLS=get_transactions,get_accounts

Tools

Authentication / session

| Tool | Groups | Description | | -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------ | | check_authentication | readonly, manage | Verify the on-disk session is valid (calls Monarch's me); returns setup instructions if not authenticated. | | monarch_login_with_token | manage | Persist a pre-obtained session token to encrypted disk storage. |

Accounts

| Tool | Groups | Description | | ----------------------------- | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_accounts | readonly, manage | List every connected account with balances and metadata. Pass includeHoldings: true to attach investment holdings to each account. | | get_account_balance_history | readonly, manage | Daily balance snapshots for one account over a date range. | | set_account_balance_history | manage | Set recorded daily balance snapshots for a manual account — range mode (start/end/balance) or explicit { date, balance } list. Per-date upsert via Monarch's balance-history importer. | | refresh_accounts | manage | Trigger an upstream institution sync. |

Net worth

| Tool | Groups | Description | | --------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- | | get_net_worth | readonly, manage | Net worth view. view: "history" (default) returns a time series; view: "by_type" returns a current breakdown by account type. |

Transactions (read)

| Tool | Groups | Description | | ------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_transactions | readonly, manage | Query transactions in five shapes via view: list (default, paged with filters), summary (aggregate totals), cashflow (income/expense/savings), by_category (totals per category), recurring (forecasted occurrences). | | get_transaction_details | readonly, manage | Full detail for a single transaction, including its splits. |

Transactions (write)

| Tool | Groups | Description | | -------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | create_transaction | manage | Create a manual transaction. | | update_transaction | manage | Patch a transaction. Supports amount / date / merchantId / categoryId / notes / hideFromReports / reviewed / tagIds in any combination. Pass bulkTransactionIds + categoryId to bulk-recategorize many transactions in one call. | | delete_transaction | manage | Permanently delete a transaction. | | split_transaction | manage | Split a transaction into multiple categorized parts. |

Categories & tags

| Tool | Groups | Description | | ---------------- | -------------------- | --------------------------------------------------------------------------------------------- | | get_categories | readonly, manage | List all categories. Pass includeGroups: true to also return the top-level category groups. | | get_tags | readonly, manage | List all tags. | | create_tag | manage | Create a tag. Requires name and a hex color (e.g. #19d2a5); order is server-assigned. | | delete_tag | manage | Delete a tag by id. Returns { deleted, errors }; deleted is confirmed by re-reading. |

Transaction rules (auto-classification)

| Tool | Groups | Description | | ------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | get_transaction_rules | readonly, manage | List configured auto-classify rules, including each rule's criteria and actions. | | create_transaction_rule | manage | Create a rule from one or more criteria (merchant / amount / category / account) plus one or more match actions. | | update_transaction_rule | manage | Update a rule by id. Full replace — re-supply the rule's complete criteria and actions (≥1 of each); any field you omit is cleared from the rule. | | delete_transaction_rule | manage | Permanently delete a rule by id. |

Budgets

| Tool | Groups | Description | | ------------------- | -------------------- | ------------------------------------- | | get_budgets | readonly, manage | List configured budgets. | | set_budget_amount | manage | Set the budget amount for a category. |

Quick Start

Install

npx monarch-money-mcp-server

Authenticate

# Clone the repo, cd into this server, then:
cd local
npm run login
# Prompts for email, password, TOTP — writes encrypted token to ~/.monarch-money-mcp/session.enc

Claude Desktop configuration

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "monarch-money": {
      "command": "npx",
      "args": ["-y", "monarch-money-mcp-server"]
    }
  }
}

Restart Claude Desktop and you should be ready. The server reads the encrypted session file from disk — no env vars are required for normal use.

Environment Variables

| Variable | Required | Description | Default | | ----------------------------- | -------- | ------------------------------------------------------------------------------------------------------ | --------------------------------- | | MONARCH_SESSION_TOKEN | No | Pre-obtained session token; resolved at startup and persisted to disk on first run. | (none) | | MONARCH_EMAIL | No | Email address for env-var login (paired with MONARCH_PASSWORD). | (none) | | MONARCH_PASSWORD | No | Password for env-var login. | (none) | | MONARCH_TOTP | No | TOTP code (only if 2FA is enabled). | (none) | | MONARCH_EMAIL_OTP | No | Email OTP code (only on first login from a new install). | (none) | | MONARCH_SESSION_PASSPHRASE | No | Override the encryption passphrase used for the on-disk session file. | monarch-mcp:${HOSTNAME}:${USER} | | MONARCH_STATE_DIR | No | Override the directory where session.enc lives. | ~/.monarch-money-mcp | | MONARCH_ENABLED_TOOL_GROUPS | No | Comma-separated list of groups to expose (readonly, manage). Defaults to all groups. | (all) | | MONARCH_ENABLED_TOOLS | No | Comma-separated whitelist of tool names. When set, takes precedence over groups and the disabled list. | (none) | | MONARCH_DISABLED_TOOLS | No | Comma-separated blacklist of tool names. Removes specific tools after group filtering is applied. | (none) |

Security Considerations

• No password through MCP tools. Authentication happens via the CLI login script or env vars, never through a tool input. Tool inputs may end up in transcripts and prompt caches; passwords don't belong there.
• Session file is encrypted at rest with AES-256-GCM. The default passphrase (host + user) ties the file to the machine that wrote it.
• Tool group filtering is the primary write-protection mechanism. Set MONARCH_ENABLED_TOOL_GROUPS=readonly for a strict read-only deployment.
• Read tools are not gated. Reading account/transaction data is unrestricted once the session is unlocked. If you need read-side approval, run the server behind a client that wraps tool calls in its own confirmation flow.

Development

Project Structure

monarch-money/
├── local/                   # Stdio entry point
│   └── src/
│       ├── index.ts                       # Production entry
│       └── index.integration-with-mock.ts # Integration test entry
├── shared/                  # Business logic
│   └── src/
│       ├── server.ts        # MCP server factory
│       ├── tools.ts         # Tool registration glue + group filtering
│       ├── tools/           # One file per tool group
│       ├── monarch-client/  # GraphQL transport + session store
│       └── types.ts
├── scripts/
│   └── login.ts             # Email/password/TOTP CLI flow
└── tests/
    ├── functional/          # Unit tests with mocked client
    ├── integration/         # Full MCP protocol with mocked Monarch
    └── e2e/                 # Hits the real Monarch GraphQL API

Running Tests

# From this directory:
npm test                  # Functional tests
npm run test:integration  # Integration tests (builds first)
npm run test:e2e          # E2E tests (requires MONARCH_SESSION_TOKEN)

License

MIT