Monarch Money MCP

🚀 Monarch Money MCP Server

An MCP (Model Context Protocol) server that offers access to Monarch Money's financial data and operations, enabling users to manage accounts, handle transactions, analyze budgets, and more.

✨ Features

• Account Management: Retrieve and list detailed account information.
• Transaction Operations: Filter and obtain transactions by date range, accounts, and categories.
• Budget Analysis: Access budget data and gain insights into spending patterns.
• Category Management: List and manage transaction categories effectively.
• Goal Tracking: Monitor financial goals and track progress over time.
• Net Worth Tracking: Retrieve net - worth snapshots at different time points.

📦 Installation

1. Clone or download this MCP server.
2. Install dependencies:

   cd /path/to/monarch-money-mcp
   uv sync
   

📚 Documentation

Configuration

Add the server to your .mcp.json configuration file:

{
  "mcpServers": {
    "monarch-money": {
      "command": "/path/to/uv",
      "args": [
        "--directory", 
        "/path/to/monarch-money-mcp",
        "run",
        "python",
        "server.py"
      ],
      "env": {
        "MONARCH_EMAIL": "your-email@example.com",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

⚠️ Important Note

• Replace /path/to/uv with the full path to your uv executable (find it with which uv).
• Replace /path/to/monarch-money-mcp with the absolute path to this server directory.
• Use absolute paths, not relative paths.

Getting Your MFA Secret

1. Navigate to Monarch Money settings and enable 2FA.
2. When the QR code is displayed, look for the "Can't scan?" or "Enter manually" option.
3. Copy the secret key (it will be a string like T5SPVJIBRNPNNINFSH5W7RFVF2XYADYX).
4. Use this as your MONARCH_MFA_SECRET.

Available Tools

get_accounts

List all accounts along with their balances and detailed information.

get_transactions

Retrieve transactions with optional filtering:

• start_date: Filter transactions starting from this date (YYYY - MM - DD).
• end_date: Filter transactions up to this date (YYYY - MM - DD).
• account_ids: List of account IDs for filtering.
• category_ids: List of category IDs for filtering.
• limit: Maximum number of transactions to return.

get_categories

List all transaction categories.

get_budgets

Access budget information and spending analysis.

get_goals

List financial goals and their progress.

get_cashflow

Retrieve cash - flow data for income and expense analysis.

get_investments

Get investment account details and performance.

get_net_worth

Retrieve net - worth snapshots over time.

💻 Usage Examples

Basic Usage

Use the get_accounts tool to see all my accounts and their current balances.

Advanced Usage

Get all transactions from January 2024 using get_transactions with start_date "2024-01-01" and end_date "2024-01-31".

Show me my current budget status using the get_budgets tool.

Session Management

The server automatically manages authentication sessions:

• Sessions are cached in a .mm directory for faster subsequent logins.
• The session cache is automatically created and managed.
• Use MONARCH_FORCE_LOGIN=true in the env section to force a fresh login if needed.

Troubleshooting

MFA Issues

• Ensure your MFA secret is correct and properly formatted.
• Try setting MONARCH_FORCE_LOGIN=true in your .mcp.json env section.
• Check that your system time is accurate (required for TOTP).

Connection Issues

• Verify your email and password are correct in .mcp.json.
• Check your internet connection.
• Try running the server directly to see detailed error messages:

  uv run server.py
  

Session Problems

• Delete the .mm directory to clear cached sessions.
• Set MONARCH_FORCE_LOGIN=true in your .mcp.json env section temporarily.

Credits

MCP Server

• Author: Taurus Colvin (@colvint)
• Description: MCP (Model Context Protocol) server wrapper for Monarch Money

MonarchMoney Python Library

• Author: hammem (@hammem)
• Repository: https://github.com/hammem/monarchmoney
• License: MIT License
• Description: The underlying Python library that provides API access to Monarch Money

This MCP server wraps the monarchmoney Python library to provide seamless integration with AI assistants through the Model Context Protocol.

Security Notes

• Keep your credentials secure in your .mcp.json file.
• The MFA secret provides full access to your account - treat it like a password.
• Session files in the .mm directory contain authentication tokens - keep them secure.
• Consider restricting access to your .mcp.json file since it contains sensitive credentials.