Monarch Money MCP Server

Although it can be used as a standalone, this is a submodule for the MCP repository.

A Model Context Protocol (MCP) server that enables AI assistants to interact with your Monarch Money personal finance data. Manage accounts, transactions, budgets, and analyze your finances programmatically.

• Email/password login with MFA support
• Session persistence (sessions last ~90 days)
• Automatic session management

• View all linked accounts (banks, credit cards, investments, etc.)
• Get account balance history
• View investment holdings
• Create/update/delete manual accounts
• Refresh account data

• Search and filter transactions
• Create, update, and delete transactions
• Split transactions across categories
• Add tags and categories
• Get transaction summaries

• View and set budgets by category
• Get cashflow summaries
• Analyze spending by category and merchant
• Track income vs expenses

• Manage categories and tags
• View recurring transactions
• Link to financial institutions

npm install
npm run build

Set these environment variables for automatic authentication:

export MONARCH_EMAIL="your@email.com"
export MONARCH_PASSWORD="your_password"
export MONARCH_MFA_SECRET="your_mfa_secret_key"  # Optional

Getting your MFA Secret Key:

1. Go to Monarch Money Settings → Security
2. Enable MFA
3. Copy the "Two-factor text code" (TOTP secret)
4. Use this as your MONARCH_MFA_SECRET

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "monarch-money": {
      "command": "node",
      "args": ["/path/to/monarch-money-mcp/dist/index.js"],
      "env": {
        "MONARCH_EMAIL": "your@email.com",
        "MONARCH_PASSWORD": "your_password",
        "MONARCH_MFA_SECRET": "your_mfa_secret"
      }
    }
  }
}

// Login manually
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_login",
  arguments: {
    email: "your@email.com",
    password: "your_password",
    mfa_secret_key: "optional_mfa_secret"
  }
});

// Check authentication status
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_check_auth"
});

// Get all accounts
const accounts = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_accounts"
});

// Get account balance history
const history = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_account_history",
  arguments: {
    account_id: "account-uuid",
    start_date: "2025-01-01",
    end_date: "2025-01-31"
  }
});

// Get recent transactions
const transactions = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_transactions",
  arguments: {
    limit: 50,
    start_date: "2025-01-01",
    end_date: "2025-01-31"
  }
});

// Create a new transaction
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_create_transaction",
  arguments: {
    amount: -45.50,
    date: "2025-02-01",
    account_id: "account-uuid",
    merchant_name: "Coffee Shop",
    category_id: "category-uuid",
    notes: "Morning coffee"
  }
});

// Update existing transaction
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_update_transaction",
  arguments: {
    transaction_id: "transaction-uuid",
    category_id: "new-category-uuid",
    notes: "Updated note"
  }
});

// Split a transaction
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_update_transaction_splits",
  arguments: {
    transaction_id: "transaction-uuid",
    splits: [
      { amount: -30.00, category_id: "groceries-uuid" },
      { amount: -15.00, category_id: "household-uuid" }
    ]
  }
});

// Get current budgets
const budgets = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_budgets"
});

// Set a budget
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_set_budget_amount",
  arguments: {
    category_id: "category-uuid",
    amount: 500.00,
    date: "2025-02-01"
  }
});

// Get cashflow summary
const cashflow = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_cashflow",
  arguments: {
    start_date: "2025-01-01",
    end_date: "2025-01-31"
  }
});

// Analyze spending by category
const byCategory = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_cashflow_by_category",
  arguments: {
    start_date: "2025-01-01",
    end_date: "2025-01-31"
  }
});

// Top merchants
const byMerchant = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_cashflow_by_merchant",
  arguments: {
    start_date: "2025-01-01",
    end_date: "2025-01-31",
    limit: 10
  }
});

// Get all categories
const categories = await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_get_categories"
});

// Create a new category
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_create_category",
  arguments: {
    name: "Side Projects",
    icon: "💻"
  }
});

// Create and apply tags
await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_create_tag",
  arguments: {
    name: "Business Expense",
    color: "#4CAF50"
  }
});

await use_mcp_tool({
  server_name: "monarch-money",
  tool_name: "monarch_set_transaction_tags",
  arguments: {
    transaction_id: "transaction-uuid",
    tag_ids: ["tag-uuid-1", "tag-uuid-2"]
  }
});

• monarch_login - Login with email/password (supports MFA)
• monarch_check_auth - Check authentication status

• monarch_get_accounts - Get all accounts
• monarch_get_account_history - Get balance history
• monarch_get_account_holdings - Get investment holdings
• monarch_get_account_types - List account types
• monarch_create_manual_account - Create manual account
• monarch_update_account - Update account details
• monarch_delete_account - Delete account
• monarch_refresh_accounts - Sync with institutions

• monarch_get_transactions - Search transactions
• monarch_get_transaction_details - Get transaction details
• monarch_get_transaction_splits - Get split information
• monarch_get_transactions_summary - Get summary stats
• monarch_create_transaction - Create transaction
• monarch_update_transaction - Update transaction
• monarch_delete_transaction - Delete transaction
• monarch_update_transaction_splits - Split transaction

• monarch_get_budgets - Get all budgets
• monarch_set_budget_amount - Set/update budget

• monarch_get_cashflow - Get cashflow summary
• monarch_get_cashflow_by_category - Breakdown by category
• monarch_get_cashflow_by_merchant - Breakdown by merchant

• monarch_get_categories - Get categories
• monarch_get_tags - Get tags
• monarch_create_category - Create category
• monarch_delete_category - Delete category
• monarch_create_tag - Create tag
• monarch_set_transaction_tags - Apply tags

• monarch_get_recurring_transactions - View recurring transactions
• monarch_get_subscription - Subscription details
• monarch_get_institutions - Linked institutions

Production is the Home Assistant add-on.

A push to main runs two GitHub Actions:

• CI installs dependencies and builds the server.
• Release builds the Dockerfile for aarch64 and amd64, pushes those images to GHCR, and commits the new version into monarch_mcp/config.yaml. That version-only commit does not start another release.

Images:

The repo is private, so the packages are private too. After the first release, either make those two packages public, or give Home Assistant a GitHub token that can read packages. Then, in the add-on store, add this repository (https://github.com/canfie1d/monarch-mcp-server), install Monarch Money MCP, and turn on automatic updates.

Add-on options are written to the process environment on start: OAUTH_SIGNING_SECRET, OAUTH_PASSPHRASE, PUBLIC_URL, and the Monarch session cookies (MONARCH_SESSION_ID, MONARCH_CSRF_TOKEN). PUBLIC_URL must be the public origin Claude uses to reach the server.

npm run build

npm run inspector

• Session Storage: Sessions are stored in ~/.monarch_session.json
• Credentials: Never commit credentials to version control
• MFA Recommended: Always enable MFA on your Monarch Money account
• Environment Variables: Use environment variables or secure secret management

1. Get budgets for current month
2. Get actual spending by category
3. Identify over-budget categories
4. Adjust budgets as needed

1. Get uncategorized transactions
2. Update categories based on merchant
3. Add tags for tracking
4. Split transactions if needed

1. Get cashflow over time periods
2. Analyze spending trends
3. Identify top expenses
4. Track savings rate

1. Create manual accounts for cash/assets
2. Update balances regularly
3. Track investment holdings
4. Monitor account history

• Verify email/password are correct
• Check MFA secret key if using auto-MFA
• Try deleting ~/.monarch_session.json and re-logging in

• Check Monarch Money API status
• Verify account UUIDs are correct
• Ensure dates are in YYYY-MM-DD format

• Sessions typically last ~90 days
• Re-authenticate if receiving 401 errors
• Save session after successful login

Built with:

• @modelcontextprotocol/sdk - MCP TypeScript SDK
• axios - HTTP client
• zod - Schema validation
• otplib - TOTP for MFA

Inspired by community Python libraries for Monarch Money API access.

MIT

This is an unofficial MCP server for Monarch Money. It is not affiliated with, endorsed by, or connected to Monarch Money in any way. Use at your own risk.