Server data from the Official MCP Registry
Monarch Money API client with 30 MCP tools for accounts, transactions, budgets, and cashflow.
Monarch Money API client with 30 MCP tools for accounts, transactions, budgets, and cashflow.
Valid MCP server (2 strong, 4 medium validity signals). 1 known CVE in dependencies (1 critical, 0 high severity) Package registry verified. Imported from the Official MCP Registry.
4 files analyzed · 2 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Set these up before or after installing:
Environment variable: MONARCH_TOKEN
Add this to your MCP configuration file:
{
"mcpServers": {
"io-github-hakimelek-monarchmoney": {
"env": {
"MONARCH_TOKEN": "your-monarch-token-here"
},
"args": [
"-y",
"@hakimelek/monarchmoney"
],
"command": "npx"
}
}
}From the project's GitHub README.
Node.js/TypeScript library for accessing Monarch Money data.
Disclaimer: This project is unofficial and not affiliated with Monarch Money.
npm install @hakimelek/monarchmoney
Requires Node.js 18+ (uses native fetch and AbortSignal.timeout).
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);
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.
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);
}
}
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.
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
await mm.interactiveLogin(); // prompts for email, password, email OTP or MFA code
All methods return typed responses. Hover over any method in your editor for full JSDoc and type information.
| Method | Returns | Description |
|---|---|---|
getAccounts() | GetAccountsResponse | All linked accounts |
getAccountTypeOptions() | GetAccountTypeOptionsResponse | Available account types/subtypes |
getRecentAccountBalances(startDate?) | GetRecentAccountBalancesResponse | Daily balances (default: last 31 days) |
getAccountSnapshotsByType(startDate, timeframe) | GetSnapshotsByAccountTypeResponse | Snapshots by type ("year" / "month") |
getAggregateSnapshots(options?) | GetAggregateSnapshotsResponse | Aggregate net value over time |
getAccountHoldings(accountId) | GetAccountHoldingsResponse | Securities in a brokerage account |
getAccountHistory(accountId) | AccountHistorySnapshot[] | Daily balance history |
getInstitutions() | GetInstitutionsResponse | Linked institutions |
getBudgets(startDate?, endDate?) | GetBudgetsResponse | Budgets with actuals (default: last month → next month) |
getSubscriptionDetails() | GetSubscriptionDetailsResponse | Plan status (trial, premium, etc.) |
getTransactionsSummary() | GetTransactionsSummaryResponse | Aggregate summary |
getTransactions(options?) | GetTransactionsResponse | Transactions with full filtering |
getAllTransactions(options?) | Transaction[] | All matching transactions (auto-paginates) |
getTransactionPages(options?) | AsyncGenerator<Transaction[]> | Async generator yielding pages |
getTransactionCategories() | GetTransactionCategoriesResponse | All categories |
getTransactionCategoryGroups() | GetTransactionCategoryGroupsResponse | Category groups |
getTransactionDetails(id) | typed response | Single transaction detail |
getTransactionSplits(id) | typed response | Splits for a transaction |
getTransactionTags() | GetTransactionTagsResponse | All tags |
getCashflow(options?) | GetCashflowResponse | Cashflow by category, group, merchant |
getCashflowSummary(options?) | GetCashflowSummaryResponse | Income, expense, savings, savings rate |
getRecurringTransactions(start?, end?) | GetRecurringTransactionsResponse | Upcoming recurring transactions |
isAccountsRefreshComplete(ids?) | boolean | Check refresh status |
| Method | Returns | Description |
|---|---|---|
createManualAccount(params) | CreateManualAccountResponse | Create manual account |
updateAccount(id, updates) | UpdateAccountResponse | Update account settings/balance |
deleteAccount(id) | DeleteAccountResponse | Delete account |
requestAccountsRefresh(ids) | boolean | Start refresh (non-blocking) |
requestAccountsRefreshAndWait(opts?) | boolean | Refresh and poll until done |
createTransaction(params) | CreateTransactionResponse | Create transaction |
updateTransaction(id, updates) | UpdateTransactionResponse | Update transaction |
deleteTransaction(id) | boolean | Delete transaction |
updateTransactionSplits(id, splits) | UpdateTransactionSplitResponse | Manage splits |
createTransactionCategory(params) | CreateCategoryResponse | Create category |
deleteTransactionCategory(id, moveTo?) | boolean | Delete category |
deleteTransactionCategories(ids) | (boolean | Error)[] | Bulk delete |
createTransactionTag(name, color) | CreateTransactionTagResponse | Create tag |
setTransactionTags(txId, tagIds) | SetTransactionTagsResponse | Set tags on transaction |
setBudgetAmount(params) | SetBudgetAmountResponse | Set/clear budget |
uploadAccountBalanceHistory(id, csv) | void | Upload balance history CSV |
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"
}
}
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.
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.).
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)`);
},
});
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.
Get your Monarch Money auth token by logging in with the library (see Authentication) and saving mm.token.
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
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.
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
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 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)
MONARCH_EMAIL=your@email.com 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).
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.
There are several unofficial Monarch Money integrations. Here's how @hakimelek/monarchmoney stacks up.
| @hakimelek/monarchmoney | monarch-money-api (pbassham) | monarchmoney (keithah) | monarchmoney (hammem) | |
|---|---|---|---|---|
| Platform | Node.js / TypeScript | Node.js / JavaScript | Node.js / TypeScript | Python |
| npm weekly downloads | — | ~440 | ~130 | N/A (pip: ~103K/mo) |
| Runtime deps | 1 (speakeasy) | 5 | 7 | 3 |
| TypeScript types | Full (every response) | None | Yes | N/A |
| Email OTP flow | Yes | No | No | No |
| MFA / TOTP | Yes | Yes | Yes | Yes |
| Session persistence | Yes (0o600 perms) | Yes | Yes (AES-256) | Yes |
| Interactive CLI login | Yes | Yes | Yes | Yes |
| HTTP client | Native fetch | node-fetch | node-fetch + graphql-request | aiohttp |
| Error hierarchy | 4 typed exceptions | Generic throws | Generic throws | 1 exception |
| Read methods | 20 | 15 | ~20 | ~16 |
| Write methods | 14 | 9 | ~12 | ~10 |
| Rate limiting | Yes | No | Yes | No |
| Retry with backoff | Yes | No | Yes | No |
| Auto-pagination | Yes | No | No | No |
| Dual CJS + ESM | Yes | No | Yes | No |
| Refresh progress events | Yes | No | No | No |
| Built-in MCP server | Yes (30 tools) | No | No | No |
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.
Contributions welcome. Please ensure TypeScript compiles cleanly (npm run build) and tests pass (npm test).
MIT
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally
by mcp-marketplace · Finance
Free stock data and market news for any MCP-compatible AI assistant.