Agent skill

monarch-money

TypeScript library and CLI for Monarch Money budget management. Search transactions by date/merchant/amount, update categories, list accounts and budgets, manage authentication. Use when user asks about Monarch Money transactions, wants to categorize spending, needs to find specific transactions, or wants to automate budget tasks.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/monarch-money

Metadata

Additional technical details for this skill

clawdbot 
{
    "install": [
        {
            "id": "node",
            "bins": [
                "monarch-money"
            ],
            "kind": "node",
            "label": "Install Monarch Money CLI",
            "package": "."
        }
    ],
    "requires": {
        "env": [
            "MONARCH_EMAIL",
            "MONARCH_PASSWORD",
            "MONARCH_MFA_SECRET"
        ]
    }
}

SKILL.md

Monarch Money

CLI and TypeScript library for Monarch Money budget automation.

Prerequisites

Environment Variables (Required)

Variable Required Description
MONARCH_EMAIL Yes Monarch Money account email
MONARCH_PASSWORD Yes Monarch Money account password
MONARCH_MFA_SECRET Yes TOTP secret for MFA (see below)

Getting Your MFA Secret

Monarch Money requires MFA. Generate the TOTP secret:

  1. Login to https://app.monarchmoney.com
  2. Go to Settings > Security > Two-Factor Authentication
  3. If MFA is already enabled: disable and re-enable to get a new secret
  4. When shown the QR code: click "Can't scan? View setup key"
  5. Copy the secret key (base32 string like JBSWY3DPEHPK3PXP)
  6. Complete MFA setup in Monarch Money with an authenticator app
  7. Set the secret: export MONARCH_MFA_SECRET="YOUR_SECRET"

Quick Start

bash
# Check setup
monarch-money doctor

# Login (uses env vars by default)
monarch-money auth login

# List transactions
monarch-money tx list --limit 10

# List categories
monarch-money cat list

CLI Commands

Authentication

bash
# Login with environment variables
monarch-money auth login

# Login with explicit credentials
monarch-money auth login -e email@example.com -p password --mfa-secret SECRET

# Check auth status
monarch-money auth status

# Logout
monarch-money auth logout

Transactions

bash
# List recent transactions
monarch-money tx list --limit 20

# Search by date
monarch-money tx list --start-date 2026-01-01 --end-date 2026-01-31

# Search by merchant
monarch-money tx list --merchant "Walmart"

# Get transaction by ID
monarch-money tx get <transaction_id>

# Update category
monarch-money tx update <id> --category <category_id>

# Update merchant name
monarch-money tx update <id> --merchant "New Name"

# Add notes
monarch-money tx update <id> --notes "My notes here"

Categories

bash
# List all categories
monarch-money cat list

# List with IDs (for updates)
monarch-money cat list --show-ids

Accounts

bash
# List accounts
monarch-money acc list

# Show account details
monarch-money acc get <account_id>

Doctor (Diagnostics)

bash
# Run diagnostic checks
monarch-money doctor

Checks:

  • Environment variables set
  • API connectivity
  • Session validity
  • Node.js version

Library Usage

Import and use the TypeScript library directly:

typescript
import { MonarchClient } from 'monarch-money';

const client = new MonarchClient({ baseURL: 'https://api.monarch.com' });

// Login
await client.login({
  email: process.env.MONARCH_EMAIL,
  password: process.env.MONARCH_PASSWORD,
  mfaSecretKey: process.env.MONARCH_MFA_SECRET
});

// Get transactions
const transactions = await client.transactions.getTransactions({ limit: 10 });

// Get categories
const categories = await client.categories.getCategories();

// Get accounts
const accounts = await client.accounts.getAll();

Common Workflows

Find and Update a Transaction

bash
# 1. Find the transaction
monarch-money tx list --date 2026-01-15 --merchant "Target"

# 2. Get category ID
monarch-money cat list --show-ids

# 3. Update the transaction
monarch-money tx update <transaction_id> --category <category_id>

Search Transactions by Date Range

bash
monarch-money tx list --start-date 2026-01-01 --end-date 2026-01-31 --limit 100

Check Budget Status

bash
monarch-money acc list

Error Handling

Error Solution
"Not logged in" Run monarch-money auth login
"MFA code required" Set MONARCH_MFA_SECRET environment variable
"Invalid credentials" Verify email/password work at app.monarchmoney.com
"Session expired" Run monarch-money auth login again

Session Management

Sessions are cached locally at ~/.mm/session.json. After initial login, subsequent commands reuse the saved session for faster execution.

To clear the session: monarch-money auth logout

Automation Workflows

Weekly Reconciliation (Cron: Sunday 9am)

Automatically reviews recent transactions and sends Telegram summary of:

  • Transactions that look miscategorized
  • Uncategorized transactions needing review

Manual Review

bash
# Review last 30 days of transactions
cd skills/monarch-money && node dist/cli/index.js tx search --limit 50

# Search for specific merchant
node dist/cli/index.js tx search --merchant "Amazon" --limit 20

# List categories with IDs
node dist/cli/index.js cat list

Re-categorize Transactions

bash
# Find category ID
node dist/cli/index.js cat search "Gas"

# Apply category to transaction
node dist/cli/index.js tx categorize <transaction_id> <category_id>

# Update merchant name
node dist/cli/index.js tx update <id> --merchant "Corrected Name"

# Add notes
node dist/cli/index.js tx update <id> --notes "Business expense - Client X"

Auto-Categorization Rules

Edit references/categorization-rules.json to add merchant patterns:

json
{
  "gas": {
    "category": "Gas",
    "patterns": ["sheetz", "shell", "exxon"]
  }
}

References

Didn't find tool you were looking for?

Be as detailed as possible for better results