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("[email protected]", "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("[email protected]", "password", code);  } else if (e instanceof RequireMFAException) {    // TOTP-based MFA is enabled on the account    await mm.multiFactorAuthenticate("[email protected]", "password", "123456");  }}
// Fetch data — fully typed responsesconst { 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 loginmm.saveSession(); // writes to .mm/mm_session.json (mode 0o600)
// Next time, login() loads the saved session automaticallyawait 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 diskmm.loadSession();          // load from diskmm.deleteSession();        // remove the filemm.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 arrayconst 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.

2. 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 oncenpm run test:watch    # run tests in watch modenpm run test:coverage # run with coverage report

Tests use Vitest and do not require real API credentials (fetch is mocked where needed).

Test the API connection (against the live api.monarch.com):

npm run build
# Login with email + password (will prompt for email OTP code if required)[email protected] MONARCH_PASSWORD=yourpassword npm run test:connection
# Use a saved token (skips login)MONARCH_TOKEN=your-token npm run test:connection -- --token

Set these in a .env file for convenience (see .env.example).

FAQ

How do I use this if I login to Monarch via Google?

Set a password on your Monarch account at Settings > Security, then use that password with this library.

Why does Monarch ask for an email code every time I login?

Monarch requires email verification for new/unrecognized devices. After login, save the session token with mm.saveSession() or store mm.token — subsequent runs will reuse it without re-authenticating.

How This Library Compares

There are several unofficial Monarch Money integrations. Here's how @hakimelek/monarchmoney stacks up.

Landscape

Where this library wins

Minimal footprint. One runtime dependency vs 5-7 in the JS/TS alternatives. Native fetch means zero HTTP polyfills on Node 18+.

Email OTP support. Monarch now requires email verification for unrecognized devices, even when MFA is off. This is the only Node.js library that handles the full EmailOtpRequiredException → submitEmailOtp() flow. Without it, automated scripts break on first login from a new environment.

Typed everything. Every API response has a dedicated TypeScript interface — 50+ exported types covering accounts, transactions, holdings, cashflow, budgets, recurring items, and mutations. The monarch-money-api package has no types at all.

Structured error handling. Four distinct exception classes (LoginFailedException, RequireMFAException, EmailOtpRequiredException, RequestFailedException) with error codes and status codes. Competitors throw generic errors or strings.

Broader write coverage. Includes updateTransaction(), setBudgetAmount(), uploadAccountBalanceHistory(), getCashflow(), getCashflowSummary(), and getRecurringTransactions() — all missing from monarch-money-api.

Clean, flat API. One class, direct methods, no sub-objects or verbosity levels to learn. Import MonarchMoney, call methods, get typed results.

Contributing

Contributions welcome. Please ensure TypeScript compiles cleanly (npm run build) and tests pass (npm test).

License

MIT