Monarch Money

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 enabledMONARCH_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/localnpm 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.

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

# Strict read-only deploymentMONARCH_ENABLED_TOOL_GROUPS=readonly
# Deny one specific toolMONARCH_DISABLED_TOOLS=delete_transaction
# Whitelist exactly two toolsMONARCH_ENABLED_TOOLS=get_transactions,get_accounts

Tools

Authentication / session

Accounts

Net worth

Transactions (read)

Transactions (write)

Categories & tags

Transaction rules (auto-classification)

Budgets

Quick Start

Install

npx monarch-money-mcp-server

Authenticate

# Clone the repo, cd into this server, then:cd localnpm 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

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 testsnpm run test:integration  # Integration tests (builds first)npm run test:e2e          # E2E tests (requires MONARCH_SESSION_TOKEN)

License

MIT