Monarch Money MCP Server

Monarch Money MCP Server

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.

Features

🔐 Authentication

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

💰 Account 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

📊 Transaction Operations

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

📈 Budget & Cashflow

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

🏷️ Organization

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

Installation

npm install
npm run build

Configuration

Environment Variables

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

Claude Desktop Configuration

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"
      }
    }
  }
}

Usage Examples

Authentication

// 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"
});

View Accounts

// 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"
  }
});

Manage Transactions

// 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" }
    ]
  }
});

Budget Management

// 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"
  }
});

Cashflow Analysis

// 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
  }
});

Categories and Tags

// 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"]
  }
});

API Reference

Authentication Tools

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

Account Tools

• 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

Transaction Tools

• 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

Budget Tools

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

Cashflow Tools

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

Organization Tools

• 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

Other Tools

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

Development

Build

npm run build

Test with MCP Inspector

npm run inspector

Security Notes

• 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

Common Use Cases

Monthly Budget Review

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

Transaction Categorization

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

Financial Analysis

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

Account Management

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

Troubleshooting

Authentication Issues

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

GraphQL Errors

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

Session Expiration

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

Credits

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.

License

MIT

Disclaimer

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.