Monarch Money MCP Server

An MCP (Model Context Protocol) server that provides access to Monarch Money financial data and operations.

Features

Account Management: List and retrieve account information
Transaction Operations: Get transactions with filtering by date range, accounts, and categories
Budget Analysis: Access budget data and spending insights
Category Management: List and manage transaction categories
Goal Tracking: Access financial goals and progress
Net Worth Tracking: Retrieve net worth snapshots over time

Installation

Clone or download this MCP server
Install dependencies:
```
cd /path/to/monarch-money-mcp
uv sync
```

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": "[email protected]",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

Important Notes:

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
Do not keep server.py running manually in an interactive terminal. This MCP server is stdio-only and should be spawned by your MCP client over pipes.
Interactive launches now refuse to start by default to avoid duplicate long-lived Python processes and EDR false positives.
If you intentionally need a one-off manual launch for debugging, set MONARCH_ALLOW_INTERACTIVE_SERVER=1.

Getting Your MFA Secret

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

Available Tools

`get_accounts`

List all accounts with their balances and details.

`get_transactions`

Get transactions with optional filtering:

start_date: Filter transactions from this date (YYYY-MM-DD)
end_date: Filter transactions to this date (YYYY-MM-DD)
account_ids: List of account IDs to filter by
category_ids: List of category IDs to filter by
limit: Maximum number of transactions to return

`get_categories`

List all transaction categories.

`get_budgets`

Get budget information and spending analysis.

`get_goals`

List financial goals and their progress.

`get_cashflow`

Get cashflow data for income and expense analysis.

`get_investments`

Get investment account details and performance.

`get_net_worth`

Get net worth snapshots over time.

Usage Examples

Basic Account Information

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

Transaction Analysis

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

Rule Candidate Analysis

Use the CLI: uv run python -m monarch.sync rule-candidates --months 6

Review Resolution

Use the CLI: uv run python -m monarch.update resolve-review
Use the CLI: uv run python -m monarch.update bulk-categorize OpenAI "AI & Infra" --months 18 --exact --negative-only --yes

Daily Dashboard

Use the CLI: uv run python -m monarch.sync dashboard

Scheduled Maintenance

Use the CLI: uv run python -m monarch.maintain --dry-run
Use the CLI: uv run python -m monarch.maintain --refresh
Use the CLI: uv run python -m monarch.maintain --json
Use the CLI: uv run python -m monarch.scheduler install-launchd --hour 9 --minute 0
Use the CLI: uv run python -m monarch.scheduler status
Use the CLI: uv run python -m monarch.scheduler run-job --dry-run
Use the CLI: uv run python -m monarch.scheduler uninstall-launchd
Use the CLI: uv run python -m monarch.codex_audit run-agent
Use the CLI: uv run python -m monarch.codex_audit install-launchd --weekday 1 --hour 12 --minute 0
Use the CLI: uv run python -m monarch.codex_audit status
Use the CLI: uv run python -m monarch.codex_audit uninstall-launchd

Repo Policy Overrides

Edit monarch-policies.json to encode merchant exceptions that should not become broad Monarch rules.
Example: a one-off merchant gift purchase can map to Gifts in the scheduler without creating a permanent in-app merchant rule.

Rule Management

Use the CLI: uv run python -m monarch.rules list
Use the CLI: uv run python -m monarch.rules preview --merchant "Target" --category Shopping
Use the CLI: uv run python -m monarch.rules update RULE_ID --category Shopping --dry-run

Category Management

Use the CLI: uv run python -m monarch.categories list --group Business
Use the CLI: uv run python -m monarch.categories create --group Business --name "AI & Infra" --icon "🤖" --budget 250 --future

Budget Tracking

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
If you need a one-off manual debug launch, explicitly allow it:
```
MONARCH_ALLOW_INTERACTIVE_SERVER=1 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

launchd Automation

The local scheduler writes summaries to ~/Library/Application Support/monarch-money-mcp/maintain/
The latest human-readable successful summary is ~/Library/Application Support/monarch-money-mcp/maintain/latest-summary.txt
The latest machine-readable successful summary is ~/Library/Application Support/monarch-money-mcp/maintain/latest-summary.json
The latest failure artifacts are ~/Library/Application Support/monarch-money-mcp/maintain/latest-error.txt and latest-error.json
stdout and stderr logs live in ~/Library/Logs/monarch-money-mcp/
Both automation surfaces prune old run artifacts and trim logs so they do not grow without bound

Install the LaunchAgent with:

uv run python -m monarch.scheduler install-launchd --hour 9 --minute 0

Codex Audit Automation

The weekly engineering agent writes artifacts to ~/Library/Application Support/monarch-money-mcp/codex-audit/
It is allowed to improve repo code, but not to mutate live Monarch data
Its structured prompt lives in automation/codex-audit-prompt.md
Its output contract lives in automation/codex-audit-output.schema.json

Install it for Monday noon with:

uv run python -m monarch.codex_audit install-launchd --weekday 1 --hour 12 --minute 0

status now reports an explicit health line so stale or failing automation is easier to spot

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 .mm directory contain authentication tokens - keep them secure
Consider restricting access to your .mcp.json file since it contains sensitive credentials