Monarch MCP Server

Summarize monthly trends, category expenses, account usage, and budget data. Args: lookback_months: Months before today to include (default: 6). include_forecasting: Include average-based income and expense estimates. verbose: Include full budget details instead of monthly budget totals. Requests one page of up to 2000 transactions, without pagination; analysis can be incomplete for larger periods. Transfers such as card payments are left out of every section and counted in metadata.transfers_excluded (null when categories could not be read). Forecasts average the latest three complete calendar months with transactions, excluding the current month. The confidence label is fixed, not a statistical measure. Failed transaction, category, or budget requests appear in errors; successful analysis sections remain available. metadata.transactions_truncated reports whether more transactions exist (null when unknown). Fetch narrower date ranges with get_transactions for detail.

Create a manually tracked account and return its new ID. Args: account_name: Display name for the account. account_type: Monarch account type name, such as loan, other_asset, or other_liability. The accounts://types resource lists valid types and subtypes. account_sub_type: Subtype name within that type, such as mortgage, auto, or line_of_credit. balance: Starting balance. include_in_net_worth: Whether the account counts toward net worth.

Create a manual transaction. Args: amount: Positive for income, negative for an expense. merchant_name: Merchant/payee display name. account_id: Account ID from get_accounts. date: Transaction date in YYYY-MM-DD format. category_id: Required category ID from get_transaction_categories. notes: Optional memo. update_balance: False records the transaction without changing the account balance. True also adjusts the balance, useful for manual accounts. Returns the created transaction details.

Create an automation rule. A rule needs at least one action and a merchant, statement, or amount criterion. Without one of those three, Monarch ignores later edits to the rule. Criteria (a transaction must match all of them; values in one list are "or"): merchant_criteria: Merchant name text, e.g. [{"operator": "contains", "value": "Corner Deli"}]. original_statement_criteria: Bank statement text, same shape. amount_criteria: {"operator": "gt"|"lt"|"eq", "value": 20} or {"operator": "between", "lower": 10, "upper": 50}. Amounts have no sign. is_expense=True (the default) matches money going out; False matches money coming in. account_ids / category_ids: Only match these accounts or current categories. Actions: set_category_id: Category ID from get_transaction_categories. set_merchant_name: New merchant name (a name, not an ID). add_tag_ids: Tag IDs to add. hide_from_reports: Hide matching transactions from reports. review_status: "needs_review" or "reviewed". apply_to_existing_transactions=True also changes matching past transactions right away. That is hard to undo, so check the criteria with search_transactions first. This tool does not change rule priority.

Create a household transaction tag and return it with its new ID. Args: name: Tag name. color: Hex color as #RRGGBB.

Delete a merchant; irreversible. Args: merchant_id: Merchant ID from get_merchants. move_to_merchant_id: Optional merchant ID from get_merchants. Moving merges the deleted merchant's transactions into this merchant.

Permanently delete a transaction by ID from get_transactions or find_duplicate_transactions.

Delete an automation rule by ID from get_transaction_rules. Transactions the rule already changed keep their current values. Deletion is confirmed by reading the rule list again.

Find possible duplicate transactions: same date, amount, statement name, and account. Args: start_date: Inclusive start; ISO or natural language. Defaults to 90 days before end_date. end_date: Inclusive end. Defaults to today. account_id: Optional account ID from get_accounts. Groups are possible duplicates only; review before deleting. Each group lists compact transactions oldest first. Hidden transactions and rows without a statement name are skipped. scan_truncated is true when the range holds more transactions than one scan reads; narrow the dates or account then.

Get a page of balance history for account_id from get_accounts. Optional YYYY-MM-DD bounds are inclusive; an omitted bound is unbounded. Filtering precedes local paging, preserving Monarch's snapshot order. limit: 1–1000 (default 100); offset: zero-based position after filtering. Follow next_offset until null. total_count counts all matching snapshots. Monarch still returns the full history upstream; the MCP response is bounded.

Get investment holdings for an account_id from get_accounts.

Retrieve all linked financial accounts.

Get holdings grouped by brokerage account, not all asset classes. Fetches accounts, then holdings for each brokerage account concurrently. A failed account request fails the entire call; this is not a single API request.

Retrieve budgets for optional start_date/end_date filters. Dates accept ISO strings or natural language such as 'last month'. A missing end defaults to today; a missing start to the first day of the end date's month.

Retrieve cash flow for optional start_date/end_date filters. Dates accept ISO strings or natural language such as 'last month'. A missing end defaults to today; a missing start to the first day of the end date's month.

Fetch a compact financial overview; verbose=True includes full API details. period is a start date or phrase such as 'this month', 'last month', or 'this year'; the end is always today. 'last month' therefore includes the current month too. Transactions and their summary use one page of up to 500 entries, not the full history. Failed API sections contain errors while successful sections remain. Default: account IDs/names/balances/types, monthly budget totals, cashflow totals, and a transaction summary. Raw transactions/categories are null unless verbose. Use their dedicated tools for details. batch_metadata.transactions_truncated is true if more transactions exist, false for a complete page, null if unknown. Summary income and expenses leave out transfers such as card payments; transfers_excluded counts them, or is null when categories could not be read.

Get household credit score snapshots, oldest first. Returns enrolled (whether credit monitoring is set up), users [{id, name}], and snapshots [{date, score, user_id}]; user_id matches a users entry.

List current household members and IDs for transaction ownership. Pending invitations are excluded. Use an ID as owner_user_id in transaction updates, or "" for Shared; a missing/null owner_user_id leaves it unchanged.

Get linked financial institutions.

List a page of merchants with transaction and rule counts. Args: limit: 1–500 (default 100). offset: Zero-based position. Follow next_offset until null. verbose: True returns the full upstream objects. Compact rows: id, name, transaction_count, rule_count, has_active_recurring_streams, can_be_deleted. Merchant IDs feed delete_merchant. total_count is Monarch's merchantCount, which may count a different set than the list; rely on next_offset.

Get net worth over time: daily totals, or monthly balances per account type. Args: start_date: Inclusive start; ISO or natural language. Defaults to one year ago. end_date: Inclusive end. Defaults to today. by_account_type: False returns daily {date, balance} totals across all accounts. True returns monthly {month, account_type, balance} rows plus account_types with each type's group (asset or liability).

List every recurring stream (merchant schedule) with its next forecast. Args: active_only: True skips paused streams. include_liabilities: True includes credit-report liability streams such as loans and cards. verbose: True returns the full upstream objects. Compact rows: id, name, merchant {id, name}, frequency, amount, is_approximate, is_active, review_status, recurring_type, base_date, next_date, next_amount, category, category_id, account, account_id. merchant.id and merchant.name feed update_recurring_transaction. Forecasts are expectations, not posted transactions.

Get scheduled recurring occurrences, not the posted transaction history. Dates accept ISO dates or natural language such as "today" or "last month". With neither date, fetch the current calendar month. With only a start, end on that month's last day. With only an end, start on the first day of that period. The recurring.recurringTransactionItems list includes each occurrence's date, amount, account, category, transactionId (when matched), and stream containing the merchant ID, frequency, and expected amount. isPast describes the date, not whether a bill was paid. Use get_transactions(is_recurring=True) for recorded transactions instead. Use get_recurring_streams for the full list of streams.

List savings goals with targets, balances, and progress. Args: include_archived: True also returns archived goals. verbose: True returns the full upstream objects. Compact goals keep whichever of these fields Monarch returns: id, name, type, status, targetAmount, currentBalance, progress, targetDate, plannedMonthlyContribution, forecastedCompletionDate, archivedAt. Goal IDs feed set_savings_goal_budget_amount.

Summarize income, expenses, and net by category, account, or month. Args: start_date: Inclusive start; accepts ISO dates or natural language. end_date: Inclusive end; accepts the same formats. A missing end defaults to today; a missing start to the first day of the end date's month. group_by: 'category', 'account', or 'month'; other values produce one group. Fetches all matching pages. Expenses are positive magnitudes. Transfers (categories in Monarch's transfer group, such as credit card payments) are left out and counted in transfers_excluded. period holds the resolved ISO dates.

List category IDs and names for lookups and transaction updates. verbose=True preserves full API details, including groups and system flags. Returns categories, count, and verbose.

Get one transaction's split linkage, amount, merchant, and category_id. Compact get_transactions/search_transactions results omit split flags. Verbose results identify split legs with isSplitTransaction but do not expose their parent IDs. This tool returns a leg's parent_transaction_id or a parent's has_split_transactions flag and split_transaction_ids. Use these IDs to fetch details for individual legs; an unsplit transaction or a split leg returns an empty list. Use this before get_transaction_splits or update_transaction_splits when you need the parent ID. transaction_id is the resolved ID returned by Monarch; it may differ from the requested ID when a pending transaction redirects to its posted replacement. Missing transactions raise an error.

Read a page of automation rules in priority order, without modifying them. limit: 1–100 (default 25); offset: zero-based position. Follow next_offset until null; count is this page and total_count is all rules. Paging is local. Compact results omit null/empty object fields and GraphQL type labels, but preserve false, zero, and active criteria/actions. verbose=True returns the full upstream objects for the requested page.

Get split legs for transaction_id from get_transactions or search_transactions. Returns transaction_id, has_split_transactions, and splits with each leg's amount, category, merchant, and notes. An unsplit transaction has an empty list.

List household transaction tags: id, name, color, transaction_count. Tag IDs feed set_transaction_tags and the tag_ids filter of get_transactions.

Fetch one page of transactions. Args: limit: Maximum transactions to request (default: 100). offset: Transactions to skip for pagination. start_date: Inclusive start; accepts ISO dates, 'last month', or '30 days ago'. Without end_date, the end defaults to today. end_date: Inclusive end, with the same date formats. Without start_date, the start defaults to the first day of the end date's month. account_id: Account ID from get_accounts. category_id: Category ID from get_transaction_categories. tag_ids: Comma-separated tag IDs. has_attachments: True for transactions with attachments, False for those without. has_notes: True for transactions with notes, False for those without. hidden_from_reports: True for hidden transactions, False for visible ones. is_split: True for split transactions, False for non-split transactions. is_recurring: True for recurring transactions, False for non-recurring ones. is_pending: True for pending transactions, False for posted transactions. needs_review: True for transactions flagged for review, False for reviewed ones. verbose: False returns compact fields; True preserves the full API objects. Boolean filters default to None (no restriction). Results contain transactions, count (this page), total_count (all matches; null if Monarch omits it), and next_offset (null when no more pages). Pass next_offset as offset for the next page. Compact fields: id, date, amount, merchant, plaidName, category, categoryId, account, needsReview; pending appears only when true, notes only when nonempty, tags (tag names) only when the transaction has tags. Amounts are negative for expenses and positive for income. Use id for updates. merchant is the display name; plaidName preserves the original statement text. category and account are names, not nested objects. Verbose results retain nested merchant/category/account objects and upstream fields such as hideFromReports, reviewStat…

Request an institution refresh for all accounts; do not wait for completion.

Search one page of transactions using Monarch's text search. Args: query: Nonempty search text for Monarch's transaction search. limit: Maximum transactions to request (default: 500). offset: Transactions to skip for pagination. start_date: Inclusive start, accepting ISO dates or natural language. Without end_date, the end defaults to today. end_date: Inclusive end. Without start_date, the start defaults to the first day of the end date's month. account_id: Account ID from get_accounts. category_id: Category ID from get_transaction_categories. tag_ids: Comma-separated tag IDs. has_attachments: Filter by attachment presence. has_notes: Filter by notes presence. hidden_from_reports: True for hidden transactions, False for visible ones. is_split: Filter by split status. is_recurring: Filter by recurring status. is_pending: True for pending transactions, False for posted transactions. needs_review: True for transactions flagged for review, False for reviewed ones. verbose: False uses get_transactions' compact fields; True keeps full API objects. Boolean filters default to None (no restriction). Returns matching transactions, search_metadata with the query, this page's result_count, and applied filters, plus total_count (all matches; null if Monarch omits it) and next_offset (null when no more pages). Pass next_offset as offset for the next page.

Set a category's monthly budget amount. Args: category_id: Category ID from get_transaction_categories. amount: Budget amount; 0 clears the budget for that month. month: Any date in the target month; ISO or natural language. Defaults to the current month. apply_to_future: True also applies the amount to later months.

Set a savings goal's planned monthly contribution. Args: goal_id: Goal ID from get_savings_goals. amount: Planned contribution for the month. month: Any date in the target month; ISO or natural language. Defaults to the current month. apply_to_future: True also applies the amount to later months.

Replace all tags on a transaction; [] removes every tag. Returns the resulting tag IDs. Args: transaction_id: Transaction ID from get_transactions or search_transactions. tag_ids: The complete tag list, as IDs from get_transaction_tags.

Update an account's settings, leaving omitted fields unchanged. Args: account_id: Account ID from get_accounts. name: New display name. balance: New balance; meant for manual accounts, since synced accounts refresh theirs. include_in_net_worth: Whether the account counts toward net worth. hide_from_summary_list: Whether to hide the account from the accounts list. hide_transactions_from_reports: Whether to exclude its transactions from budgets and reports. Provide at least one change. Returns the compact updated account.

Change a merchant's recurring schedule, not an individual transaction. This affects the merchant-wide recurrence. Get merchant_id from an occurrence's stream.merchant.id, not stream.id or transactionId. Pass the current merchant_name to avoid renaming the merchant. Omitted settings stay unchanged; provide at least one. is_recurring enables or removes recurrence; is_active pauses or resumes a schedule. frequency is Monarch's string (for example, "monthly"). base_date is the schedule's anchor date and accepts the same date formats as get_recurring_transactions. amount uses Monarch's signed amount, as returned by the existing stream. This does not create posted transactions or move money.

Update a transaction, leaving omitted fields unchanged. Args: transaction_id: Transaction ID from get_transactions or search_transactions. amount: New nonzero amount. Monarch's client cannot set an amount of 0. merchant_name: New display name, not the read-only plaidName statement text. The API ignores empty names. category_id: New category ID from get_transaction_categories. date: New date in YYYY-MM-DD format. notes: Memo, separate from the merchant name; "" clears it. goal_id: Savings goal ID; "" clears the association. hide_from_reports: Whether to hide the transaction from reports. needs_review: Whether to flag the transaction for review. owner_user_id: Member ID from get_household_members; "" makes it Shared. Omitted/null leaves ownership unchanged. Read verbose transactions to verify ownership; the update response does not include the owner. Returns updated transaction details. This tool cannot change the transaction ID, account, pending status, attachments, or timestamps. Use update_transaction_splits to change splits and update_recurring_transaction to change a merchant's recurring schedule.

Edit a rule, and optionally run it on existing transactions. Get rule_id from get_transaction_rules. Arguments you leave out keep their current value. To clear a value, pass [] for a list or "" for set_category_id, set_merchant_name, or review_status. clear_amount_criteria removes the amount criterion. A list replaces the whole old list. Shapes match create_transaction_rule. Monarch replaces the whole rule on update. So this reads the rule first and sends it back with your changes, which keeps settings this tool can't edit, such as owners, goals, and splits. The edited rule must keep at least one action and a merchant, statement, or amount criterion. apply_to_existing_transactions=True runs the rule on matching past transactions, even with no other changes. That is hard to undo.

Replace a transaction's entire set of splits, or remove all splits with []. Args: transaction_id: Parent transaction ID. For a split leg from list/search, resolve parent_transaction_id with get_transaction_details first. splits: Complete replacement list. Each leg accepts: - amount (required): Negative for expenses, positive for income. Amounts must sum to the parent's amount or Monarch rejects the update. - category_id: Category ID for the leg. - merchant_name: Display name; defaults to the parent merchant. - notes: Per-leg memo. Example for a -100.00 parent transaction: [{"amount": -70.00, "category_id": "cat_groceries", "notes": "Food"}, {"amount": -30.00, "category_id": "cat_household"}] Returns transaction_id, has_split_transactions, resulting splits, and a summary.

Update transactions concurrently, returning per-item results and counts. Args: updates: JSON array encoded as a string. Each item requires a nonempty transaction_id and accepts amount, merchant_name, category_id, date (YYYY-MM-DD), notes, goal_id, hide_from_reports, needs_review, and owner_user_id. Fields have the same meaning as update_transaction; omitted/null fields stay unchanged. Empty notes or goal_id clears that value; empty owner_user_id makes the transaction Shared. Items reject unknown fields and wrong types without coercion; amounts must be finite nonzero numbers and flags must be booleans. Invalid items fail individually; valid items still run. The batch is not atomic and does not roll back successes. Example: [{"transaction_id": "txn_123", "category_id": "cat_456", "notes": ""}, {"transaction_id": "txn_789", "needs_review": false}]