Monarchmoney

Monarch Money (Node.js)

Node.js/TypeScript library for accessing Monarch Money data.

Disclaimer: This project is unofficial and not affiliated with Monarch Money.

Installation

npm install @hakimelek/monarchmoney

Requires Node.js 18+ (uses native fetch and AbortSignal.timeout).

Quick Start

import {

MonarchMoney, EmailOtpRequiredException, RequireMFAException, } from "@hakimelek/monarchmoney";

const mm = new MonarchMoney();

try { await mm.login("your@email.com", "password"); } catch (e) { if (e instanceof EmailOtpRequiredException) { // Monarch sent a verification code to your email const code = await promptUser("Enter the code from your email:"); await mm.submitEmailOtp("your@email.com", "password", code); } else if (e instanceof RequireMFAException) { // TOTP-based MFA is enabled on the account await mm.multiFactorAuthenticate("your@email.com", "password", "123456"); } }

// Fetch data — fully typed responses const { accounts } = await mm.getAccounts(); console.log(accounts[0].displayName, accounts[0].currentBalance);

Authentication

Monarch's API requires email verification (OTP) for new devices/sessions, even when MFA is disabled. The library handles this with distinct exception types so your app can respond appropriately.

Login with email OTP handling

try {

await mm.login(email, password); } catch (e) { if (e instanceof EmailOtpRequiredException) { // A code was sent to the user's email — prompt them for it const code = await yourApp.promptForEmailCode(); await mm.submitEmailOtp(email, password, code); } }

With MFA secret key (automatic TOTP)

await mm.login("email", "password", {

mfaSecretKey: "YOUR_BASE32_SECRET", });

The MFA secret is the "Two-factor text code" from Settings > Security > Enable MFA in Monarch Money.

Session persistence & token reuse

After a successful login (including email OTP), you can save the token to avoid re-authenticating on every run:

// Save token after login

mm.saveSession(); // writes to .mm/mm_session.json (mode 0o600)

// Next time, login() loads the saved session automatically await mm.login(email, password); // uses saved token, no network call

// Or pass the token directly (skip login entirely) const mm = new MonarchMoney({ token: "your-saved-token" });

mm.saveSession();          // save to disk

mm.loadSession(); // load from disk mm.deleteSession(); // remove the file mm.setToken("..."); // set token programmatically

Interactive CLI

await mm.interactiveLogin(); // prompts for email, password, email OTP or MFA code

API

All methods return typed responses. Hover over any method in your editor for full JSDoc and type information.

Read Methods

Write Methods

Error Handling

import {

MonarchMoneyError, // base class for all errors EmailOtpRequiredException, // email verification code needed — call submitEmailOtp() RequireMFAException, // TOTP MFA required — call multiFactorAuthenticate() LoginFailedException, // bad credentials or auth error (includes .statusCode) RequestFailedException, // API/GraphQL failure (includes .statusCode, .graphQLErrors) } from "@hakimelek/monarchmoney";

try { await mm.login(email, password); } catch (e) { if (e instanceof EmailOtpRequiredException) { // e.code === "EMAIL_OTP_REQUIRED" // Prompt user for the code sent to their email const code = await getCodeFromUser(); await mm.submitEmailOtp(email, password, code); } else if (e instanceof RequireMFAException) { // e.code === "MFA_REQUIRED" // Prompt for TOTP code or use mfaSecretKey } else if (e instanceof LoginFailedException) { // e.code === "LOGIN_FAILED", e.statusCode console.error("Login failed:", e.message); } }

try { await mm.getAccounts(); } catch (e) { if (e instanceof RequestFailedException) { console.error(e.statusCode); // HTTP status, if applicable console.error(e.graphQLErrors); // GraphQL errors array, if applicable console.error(e.code); // "HTTP_ERROR" | "REQUEST_FAILED" } }

Configuration

const mm = new MonarchMoney({

sessionFile: ".mm/mm_session.json", // session file path timeout: 10, // API timeout in seconds token: "pre-existing-token", // skip login retry: { maxRetries: 3, // retry on 429/5xx (default: 3, set 0 to disable) baseDelayMs: 500, // base delay with exponential backoff + jitter }, rateLimit: { requestsPerSecond: 10, // token-bucket throttle (default: 0 = unlimited) }, });

mm.setTimeout(30); // change timeout later

Retry automatically handles transient failures (429 Too Many Requests, 500, 502, 503, 504) with exponential backoff and jitter. The Retry-After header is respected on 429 responses.

Auto-Pagination

getTransactions() returns a single page. For large datasets, use the auto-pagination helpers:

// Async generator — yields one page at a time (memory-efficient)

for await (const page of mm.getTransactionPages({ startDate: "2025-01-01", endDate: "2025-12-31" })) { for (const tx of page) { console.log(tx.merchant?.name, tx.amount); } }

// Or collect everything into a flat array const all = await mm.getAllTransactions({ startDate: "2025-01-01", endDate: "2025-12-31", pageSize: 100, // transactions per page (default: 100) }); console.log(${all.length} total transactions);

Both methods accept the same filter options as getTransactions() (date range, category, account, tags, etc.).

Refresh Progress

Track account refresh progress with the onProgress callback:

await mm.requestAccountsRefreshAndWait({

timeout: 300, delay: 10, onProgress: ({ completed, total, elapsedMs }) => { console.log(${completed}/${total} accounts refreshed (${(elapsedMs / 1000).toFixed(0)}s)); }, });

MCP Server (AI Agent Integration)

This package includes a built-in Model Context Protocol server with 30 tools, making your Monarch Money data accessible to AI assistants like Claude Desktop, Cursor, and any MCP-compatible client.

Setup

1. Get your Monarch Money auth token by logging in with the library (see Authentication) and saving mm.token.

1. Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{

"mcpServers": { "monarch-money": { "command": "npx", "args": ["@hakimelek/monarchmoney"], "env": { "MONARCH_TOKEN": "your-token-here" } } } }

Or run it directly:

MONARCH_TOKEN=your-token npx @hakimelek/monarchmoney

Available Tools

Read (18 tools): get_accounts, get_account_holdings, get_account_history, get_account_type_options, get_recent_account_balances, get_aggregate_snapshots, get_institutions, get_budgets, get_subscription_details, get_transactions, get_transactions_summary, get_transaction_details, get_transaction_categories, get_transaction_category_groups, get_transaction_tags, get_cashflow, get_cashflow_summary, get_recurring_transactions

Write (12 tools): create_transaction, update_transaction, delete_transaction, create_manual_account, update_account, delete_account, refresh_accounts, is_refresh_complete, set_budget_amount, create_transaction_tag, set_transaction_tags, create_transaction_category

Every tool has typed parameters with descriptions, so AI agents know exactly what arguments to pass.

Project Structure

src/

index.ts — public exports client.ts — MonarchMoney class with all API methods mcp.ts — MCP server (30 tools for AI agents) errors.ts — error classes (MonarchMoneyError hierarchy) endpoints.ts — API URL constants queries.ts — all GraphQL query/mutation strings types.ts — TypeScript interfaces for all API responses

Testing

npm test              # run tests once

npm run test:watch # run tests in watch mode npm run test:coverage # run with coverage report

Tests use [Vitest](https:/