# Monarch Money TypeScript SDK

A TypeScript library for accessing [Monarch Money](https://www.monarchmoney.com) data.

## Installation

```bash
bun add monarchmoney
```

or

```bash
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:

```typescript
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:

```typescript
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:

```typescript
// 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

```typescript
// 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
# 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

```bash
# Set your credentials as environment variables
export MONARCH_USER="your.email@example.com"
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:

```bash
# 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`):

```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