Monarch Money TypeScript SDK

by martinamps

2 stars

363 downloads

Not rated

GitHub

About

The Monarch Money TypeScript SDK is a library and MCP (Model Context Protocol) server that provides read-only access to Monarch Money financial data. It allows developers and AI agents to query accounts, transactions, budgets, cashflow, and more using TypeScript or through an…

Details

Author: martinamps
GitHub stars: 2
Downloads: 363
Categories: Developer Tools, Productivity, Finance

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Monarch Money TypeScript SDK

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

From the repository

Install with bun add monarchmoney or npm install monarchmoney. Authenticate using a browser token (from Monarch Money web) or email/password (optionally with MFA). Start the included MCP server via bun run mcp, or use the SDK directly in TypeScript code with methods like getAccounts().

`setup_authentication`

Get instructions for setting up secure authentication with Monarch Money.

`check_auth_status`

Check if already authenticated with Monarch Money.

`debug_session_loading`

Debug keyring session loading issues.

`get_accounts`

Get all financial accounts from Monarch Money.

`get_transactions`

Get transactions from Monarch Money. Args: limit: Number of transactions to retrieve (default: 100) offset: Number of transactions to skip (default: 0) start_date: Start date in YYYY-MM-DD format (requires end_date) end_date: End date in YYYY-MM-DD format (requires start_date) account_id: Specific account ID to filter by (shorthand for account_ids with one ID) search: Free text search query category_ids: List of category IDs to filter by account_ids: List of account IDs to filter by (cannot use with account_id) tag_ids: List of tag IDs to filter by has_attachments: Filter transactions with/without attachments has_notes: Filter transactions with/without notes hidden_from_reports: Filter transactions hidden/visible in reports is_split: Filter split/unsplit transactions is_recurring: Filter recurring/non-recurring transactions synced_from_institution: Filter synced/manual transactions

`get_budgets`

Get budget information from Monarch Money. Args: start_date: Start date in YYYY-MM-DD format (default: last month) end_date: End date in YYYY-MM-DD format (default: next month) use_v2_goals: Whether to use v2 goals format (default: True)

`get_cashflow`

Get cashflow analysis from Monarch Money. Args: start_date: Start date in YYYY-MM-DD format (requires end_date; defaults to current month) end_date: End date in YYYY-MM-DD format (requires start_date; defaults to current month)

`get_account_holdings`

Get investment holdings for a specific account. Args: account_id: The ID of the investment account

`create_transaction`

Create a new transaction in Monarch Money. Args: account_id: The account ID to add the transaction to amount: Transaction amount (positive for income, negative for expenses) merchant_name: Merchant name for the transaction category_id: Category ID for the transaction date: Transaction date in YYYY-MM-DD format notes: Optional transaction notes update_balance: Whether to update the account balance (default: False)

`update_transaction`

Update an existing transaction in Monarch Money. Args: transaction_id: The ID of the transaction to update category_id: New category ID merchant_name: New merchant name goal_id: Goal ID to associate with the transaction amount: New transaction amount date: New transaction date in YYYY-MM-DD format hide_from_reports: Whether to hide the transaction from reports needs_review: Whether the transaction needs review notes: Transaction notes

`delete_transaction`

Delete a transaction from Monarch Money. Args: transaction_id: The ID of the transaction to delete

`refresh_accounts`

Request account data refresh from financial institutions.

`get_transaction_tags`

Get all transaction tags from Monarch Money.

`create_transaction_tag`

Create a new transaction tag in Monarch Money. Args: name: Tag name (required) color: Hex RGB color including # (required, e.g., "#19D2A5")

`delete_transaction_tag`

Delete a transaction tag from Monarch Money. Args: tag_id: The ID of the tag to delete

`set_transaction_tags`

Set tags on a transaction (replaces existing tags). Args: transaction_id: Transaction UUID (required) tag_ids: List of tag IDs to apply (required, empty list removes all tags) Note: This overwrites existing tags. To remove all tags, pass an empty list.

`get_transaction_categories`

Get all transaction categories from Monarch Money.

`get_transaction_category_groups`

Get all transaction category groups from Monarch Money.

`get_transaction_details`

Get detailed information about a specific transaction. Args: transaction_id: The ID of the transaction redirect_posted: Whether to redirect to posted transaction (default: True)

`get_recurring_transactions`

Get recurring transactions from Monarch Money. Args: start_date: Start date in YYYY-MM-DD format (requires end_date) end_date: End date in YYYY-MM-DD format (requires start_date)

`get_transactions_summary`

Get aggregate transaction summary (count, sum, avg, max, income, expenses).

`get_subscription_details`

Get Monarch Money subscription status and details.

`get_institutions`

Get all connected financial institutions and their connection status.

`get_cashflow_summary`

Get cashflow summary (income, expenses, savings, savings rate). Args: limit: Number of records to retrieve (default: 100) start_date: Start date in YYYY-MM-DD format (requires end_date) end_date: End date in YYYY-MM-DD format (requires start_date)

`set_budget_amount`

Set or update a budget amount for a category or category group. Args: amount: The budget amount to set category_id: Category ID (mutually exclusive with category_group_id) category_group_id: Category group ID (mutually exclusive with category_id) timeframe: Budget timeframe - "month" or "week" (default: "month") start_date: Budget start date in YYYY-MM-DD format apply_to_future: Whether to apply this amount to future periods (default: False)

`get_transaction_splits`

Get split information for a transaction. Args: transaction_id: The ID of the transaction

`update_transaction_splits`

Create, modify, or delete splits for a transaction. Args: transaction_id: The ID of the transaction to split split_data: List of split objects, each with keys: merchantName, amount, categoryId. Sum of split amounts must equal the original transaction amount. Pass an empty list to remove all splits.

`create_transaction_category`

Create a new transaction category in Monarch Money. Args: group_id: The category group ID this category belongs to name: The category name icon: Category icon (default: question mark emoji) rollover_enabled: Whether budget rollover is enabled (default: False) rollover_type: Rollover type - "monthly" (default: "monthly") rollover_start_month: Rollover start in YYYY-MM-DD (default: 1st of month)

`delete_transaction_category`

Delete a transaction category from Monarch Money. Args: category_id: The ID of the category to delete

`create_manual_account`

Create a new manual account in Monarch Money. Args: account_name: Name for the account account_type: Account type (use get_account_type_options to see valid types) account_sub_type: Account sub-type is_in_net_worth: Whether to include in net worth calculation account_balance: Starting balance (default: 0)

`update_account`

Update an existing account in Monarch Money. Args: account_id: The ID of the account to update account_name: New account name account_balance: New account balance account_type: New account type account_sub_type: New account sub-type include_in_net_worth: Whether to include in net worth hide_from_summary_list: Whether to hide from summary list hide_transactions_from_reports: Whether to hide transactions from reports

`get_account_history`

Get historical balance snapshots for an account. Args: account_id: The ID of the account

`get_recent_account_balances`

Get daily balance for all accounts from a start date. Args: start_date: Start date in YYYY-MM-DD format (optional)

`get_account_snapshots_by_type`

Get net value snapshots grouped by account type. Args: start_date: Start date in YYYY-MM-DD format timeframe: Aggregation period - "month" or "year"

`get_aggregate_snapshots`

Get daily aggregate net value of all accounts. Args: start_date: Start date in YYYY-MM-DD format end_date: End date in YYYY-MM-DD format account_type: Filter by account type (optional)

`get_account_type_options`

Get available account types and sub-types for creating manual accounts.

`get_credit_history`

Get credit score history and related details.

`delete_account`

Delete an account from Monarch Money. This action is irreversible. Args: account_id: The ID of the account to delete

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "monarch money typescript sdk": {
            "monarch-mcp": {
                "command": "bun",
                "args": [
                    "run",
                    "example"
                ]
            }
        }
    }
}

McpServers

{
    "monarch-mcp": {
        "command": "bun",
        "args": [
            "run",
            "example"
        ]
    }
}

Monarch Money TypeScript SDK

A TypeScript library for accessing Monarch Money data.

Installation

bun add monarchmoney

npm install monarchmoney

Usage

Quick Start with Browser Token

The easiest way to get started is by using a token directly from your browser session:

import MonarchMoney from 'monarchmoney';
// You can get this token from your browser's localStorage or Cookies after logging in

// to Monarch Money on the web

const token = process.env.MONARCH_TOKEN;
// Create a client with the token

const mm = new MonarchMoney(token);
// Now you can use the API without logging in

const accounts = await mm.getAccounts();

Standard Authentication

If you don't have a token, you can log in with your credentials:

import MonarchMoney, { RequireMFAError } from 'monarchmoney';
// Create a new client

const mm = new MonarchMoney();
// Login using environment variables

const email = process.env.MONARCH_USER;

const password = process.env.MONARCH_PASSWORD;
if (!email || !password) {

  throw new Error('MONARCH_USER and MONARCH_PASSWORD environment variables must be set');

}
// Login

try {

  await mm.login({

    email,

    password

  });

} catch (error) {

  if (error instanceof RequireMFAError) {

    // Get MFA code from user

    const mfaCode = process.env.MONARCH_MFA || prompt('Enter MFA code:');

    

    await mm.authenticateWithMFA({

      email,

      password,

      mfaCode

    });

  } else {

    throw error;

  }

}

Using a Saved Session

You can save your session for later use:

// After logging in, save the session
mm.saveSession();
// Later, load the session

const mm = new MonarchMoney();

mm.loadSession();
// Now you can access data without logging in again

const accounts = await mm.getAccounts();

Accessing Data

// Get accounts
const accounts = await mm.getAccounts();
console.log(accounts);
// Get transactions for current month

const today = new Date();

const firstDayOfMonth = new Date(today.getFullYear(), today.getMonth(), 1);

const lastDayOfMonth = new Date(today.getFullYear(), today.getMonth() + 1, 0);
const transactions = await mm.getTransactions({

  limit: 10,

  filters: {

    startDate: firstDayOfMonth.toISOString().split('T')[0],

    endDate: lastDayOfMonth.toISOString().split('T')[0]

  }

});

console.log(transactions);
// Get budgets

const budgets = await mm.getBudgets();

console.log(budgets);
// Get account holdings

const holdings = await mm.getAccountHoldings('account-id-here');

console.log(holdings);

Running the Example

To run the included example, you have two options:

Option 1: Using a Browser Token (Easiest)

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

setup_authentication

check_auth_status

debug_session_loading

get_accounts

get_transactions

get_budgets

get_cashflow

get_account_holdings

create_transaction

update_transaction

delete_transaction

refresh_accounts

get_transaction_tags

create_transaction_tag

delete_transaction_tag

set_transaction_tags

get_transaction_categories

get_transaction_category_groups

get_transaction_details

get_recurring_transactions

get_transactions_summary

get_subscription_details

get_institutions

get_cashflow_summary

set_budget_amount

get_transaction_splits

update_transaction_splits

create_transaction_category

delete_transaction_category

create_manual_account

update_account

get_account_history

get_recent_account_balances

get_account_snapshots_by_type

get_aggregate_snapshots

get_account_type_options

get_credit_history

delete_account

Claude Desktop / Cursor

McpServers

Monarch Money TypeScript SDK

Installation

Usage

Quick Start with Browser Token

Standard Authentication

Using a Saved Session

Accessing Data

Running the Example

Option 1: Using a Browser Token (Easiest)

Install

More like this

Time

Sentry

Github

Git

GitLab

Context 7

`setup_authentication`

`check_auth_status`

`debug_session_loading`

`get_accounts`

`get_transactions`

`get_budgets`

`get_cashflow`

`get_account_holdings`

`create_transaction`

`update_transaction`

`delete_transaction`

`refresh_accounts`

`get_transaction_tags`

`create_transaction_tag`

`delete_transaction_tag`

`set_transaction_tags`

`get_transaction_categories`

`get_transaction_category_groups`

`get_transaction_details`

`get_recurring_transactions`

`get_transactions_summary`

`get_subscription_details`

`get_institutions`

`get_cashflow_summary`

`set_budget_amount`

`get_transaction_splits`

`update_transaction_splits`

`create_transaction_category`

`delete_transaction_category`

`create_manual_account`

`update_account`

`get_account_history`

`get_recent_account_balances`

`get_account_snapshots_by_type`

`get_aggregate_snapshots`

`get_account_type_options`

`get_credit_history`

`delete_account`