What is Monarch Mcp

monarch-mcp is a small MCP server designed for accessing Monarch Money data through a TypeScript SDK.

Use cases

Use cases include retrieving user account information, managing financial data, and integrating Monarch Money services into web applications.

How to use

To use monarch-mcp, install the library via npm or bun, then create a client using a token or by logging in with credentials. You can also save and load sessions for easier access.

Key features

Key features include easy authentication via browser tokens, standard login with MFA support, session management, and straightforward API access to user accounts and transactions.

Where to use

monarch-mcp can be used in personal finance applications, financial analytics tools, and any software that requires integration with Monarch Money for data retrieval.

Monarch Money TypeScript SDK

A TypeScript library for accessing Monarch Money data.

Installation

bun add monarchmoney

or

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)

# Get the token from your browser after logging in to Monarch Money
# In Chrome: DevTools > Application > Storage > Local Storage > monarchmoney.com > find the auth token
export MONARCH_TOKEN="your-token-from-browser"

# Run the example
bun run example

Option 2: Using Username/Password

# Set your credentials as environment variables
export MONARCH_USER="[email protected]"
export MONARCH_PASSWORD="your-password"
# Optional: Set MFA code if required
export MONARCH_MFA="123456"

# Run the example
bun run example

Available Methods

This SDK provides read-only access to Monarch Money data:

• getAccounts() - Get all accounts
• getAccountTypeOptions() - Get all account types and subtypes
• getAccountHoldings(accountId) - Get securities in a brokerage account
• getAccountHistory(accountId) - Get daily account history
• getInstitutions() - Get linked institutions
• getBudgets(startDate, endDate) - Get budgets and actual amounts
• getSubscriptionDetails() - Get account subscription status
• getTransactionsSummary() - Get transaction summary data
• getTransactions(options) - Get transaction data
• getTransactionCategories() - Get transaction categories
• getTransactionCategoryGroups() - Get transaction category groups
• getTransactionDetails(transactionId) - Get details for a transaction
• getTransactionSplits(transactionId) - Get transaction splits
• getTransactionTags() - Get transaction tags
• getCashflow(options) - Get cashflow data
• getCashflowSummary(options) - Get cashflow summary
• getRecurringTransactions(startDate, endDate) - Get recurring transactions

MCP Server for AI Agents

This SDK includes a Model Context Protocol (MCP) server that allows AI agents to interact with Monarch Money. The MCP server provides tools for querying accounts, transactions, budgets, and more.

To start the MCP server:

# Set up authentication via environment variables
export MONARCH_TOKEN="your-token-from-browser"

# Start the MCP server
bun run mcp

The MCP server will automatically authenticate using the MONARCH_TOKEN environment variable and provides the following tools:

• check_authentication - Check if already authenticated
• get_accounts - Get all accounts
• get_account_holdings - Get holdings for an account
• get_account_history - Get history for an account
• get_transactions - Get transactions with filters
• get_transaction_categories - Get transaction categories
• get_budgets - Get budgets for a date range
• get_cashflow - Get cashflow data with filters

Claude Desktop Configuration

To use this with Claude Desktop, add the following to your Claude Desktop configuration file (located at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "monarchMoney": {
      "command": "bun",
      "args": [
        "run",
        "mcp"
      ],
      "env": {
        "MONARCH_TOKEN": "your-monarch-token-here"
      },
      "cwd": "/path/to/your/monarch-ts"
    }
  }
}

Replace /path/to/your/monarch-ts with the actual path to your project directory and your-monarch-token-here with your Monarch Money token from your browser.

License

MIT