Skip to content

README.md

Latest commit

 

History

History
357 lines (267 loc) · 10.8 KB

README.md

File metadata and controls

357 lines (267 loc) · 10.8 KB

Monarch Access

Lightweight CLI and Python SDK for accessing Monarch Money financial data.

$ monarch accounts
ACCOUNTS (5)
+--------------------------------+--------------------+----------------+
| Account                        | Institution        |        Balance |
+--------------------------------+--------------------+----------------+
| [Checking]                     |                    |      $8,434.56 |
|   Primary Checking             | First National     |      $5,234.56 |
|   Joint Checking               | First National     |      $3,200.00 |
| [Credit Card]                  |                    |     -$3,148.06 |
|   Rewards Card                 | Premium Credit     |     -$2,345.67 |
|   Store Card                   | Target             |       -$802.39 |
| [Savings]                      |                    |     $12,500.00 |
|   Emergency Fund               | First National     |     $12,500.00 |
+--------------------------------+--------------------+----------------+

$ monarch transactions list --start 2025-01-01 --limit 5
TRANSACTIONS (5)
+------------+--------------------------+----------------------+--------------+
| Date       | Merchant                 | Category             |       Amount |
+------------+--------------------------+----------------------+--------------+
| 2025-01-15 | Amazon                   | Shopping             |     -$127.43 |
| 2025-01-14 | Whole Foods              | Groceries            |      -$89.23 |
| 2025-01-13 | Shell                    | Gas                  |      -$45.00 |
| 2025-01-12 | Netflix                  | Entertainment        |      -$15.99 |
| 2025-01-10 | Employer Payroll         | Salary               |    $3,500.00 |
+------------+--------------------------+----------------------+--------------+

Total: $3,222.35

Installation

pipx install git+https://github.com/krisrowe/monarch-access.git

This installs three commands:

  • monarch - The CLI tool for direct command-line use
  • monarch-mcp - The MCP server for AI assistant integration (see MCP Server)
  • monarch-admin - User management for MCP server (local and cloud)

Requirements

  • Python 3.10+
  • A Monarch Money account

Authentication

Monarch doesn't have a public API, so you need to grab your session token from the browser:

  1. Go to https://app.monarch.com/ and log in
  2. Open DevTools (F12) → Console tab
  3. Paste and run: 
    JSON.parse(JSON.parse(localStorage.getItem("persist:root")).user).token
  4. Copy the token string
  5. Register it: 
    monarch-admin connect local
monarch-admin users add local --token $MONARCH_SESSION_TOKEN

The token is stored in the local user store and used by both the CLI and MCP server. Tokens typically last several months — repeat these steps when yours expires.

CLI Usage

All commands default to text format with ASCII tables. Use --format json or --format csv for machine-readable output.

List Transactions

# Transactions since a date
monarch transactions list --start 2025-12-01

# Date range (both inclusive)
monarch transactions list --start 2025-01-01 --end 2025-12-31

# Filter by account (supports wildcards)
monarch transactions list --start 2025-01-01 --account "Chase*"

# Filter by category (comma-separated)
monarch transactions list --start 2025-01-01 --category "Shopping,Groceries"

# Filter by merchant (supports wildcards)
monarch transactions list --start 2025-01-01 --merchant "*amazon*"

# Output as JSON or CSV
monarch transactions list --start 2025-01-01 --format json
monarch transactions list --start 2025-01-01 --format csv

# Limit results (default 1000)
monarch transactions list --start 2025-01-01 --limit 50

JSON output example:

$ monarch transactions list --start 2025-01-01 --limit 1 --format json
{
  "transactions": [
    {
      "id": "311447260750935400",
      "amount": -127.43,
      "pending": false,
      "date": "2025-01-15",
      "hideFromReports": false,
      "needsReview": false,
      "plaidName": "AMAZON #7491",
      "notes": "",
      "isRecurring": false,
      "account": {
        "id": "acc_004",
        "displayName": "Rewards Card"
      },
      "merchant": {
        "id": "merch_amazon",
        "name": "Amazon"
      },
      "category": {
        "id": "cat_005",
        "name": "Shopping"
      },
      "tags": []
    }
  ],
  "count": 1,
  "total": 147
}

Get a Single Transaction

monarch transactions get TRANSACTION_ID
monarch transactions get TRANSACTION_ID --format json

Update a Transaction

# Update notes
monarch transactions update TRANSACTION_ID --notes "New note"

# Update category (by name)
monarch transactions update TRANSACTION_ID --category "Groceries"

# Update merchant
monarch transactions update TRANSACTION_ID --merchant "Amazon"

# Clear notes (use empty string)
monarch transactions update TRANSACTION_ID --notes ""

List Accounts

monarch accounts
monarch accounts --format json
monarch accounts --format csv

Net Worth Report

monarch net-worth
monarch net-worth --format json
monarch net-worth --format csv

Shows assets and liabilities grouped by category with totals.

Python SDK Usage

import asyncio
from monarch.client import MonarchClient
from monarch import accounts, categories
from monarch.transactions import list as txn_list, get as txn_get, update as txn_update

async def main():
    client = MonarchClient()

    # Get all accounts
    accts = await accounts.get_accounts(client)

    # Get transactions
    data = await txn_list.get_transactions(
        client,
        limit=100,
        start_date="2025-01-01",
        end_date="2025-12-31",
    )
    txns = data["results"]

    # Get a single transaction
    txn = await txn_get.get_transaction(client, "some-transaction-id")

    # Update a transaction
    updated = await txn_update.update_transaction(
        client,
        transaction_id="some-transaction-id",
        notes="Updated via SDK",
    )

    # Get categories
    cats = await categories.get_categories(client)

asyncio.run(main())

MCP Server for AI Assistants

The monarch-mcp command exposes Monarch data via the Model Context Protocol, enabling AI assistants like Claude and Gemini to access your financial data.

Setup

Register a local MCP user with your Monarch token:

monarch-admin connect local
monarch-admin users add local --token $MONARCH_SESSION_TOKEN

Register with Claude Code

claude mcp add --scope user monarch -- monarch-mcp stdio --user local

Register with Gemini CLI

gemini mcp add monarch -- monarch-mcp stdio --user local

Available Tools

Tool Description
list_accounts Get all accounts with balances
list_categories Get all transaction categories
list_transactions Query transactions with filters
get_transaction Get a single transaction
update_transaction Update category, notes, etc.
mark_transactions_reviewed Bulk mark as reviewed
split_transaction Split across categories
create_transaction Create manual transaction
delete_transaction Delete a transaction
list_recurring List recurring obligations
update_recurring Update recurring stream settings

For detailed documentation, see MCP-SERVER.md.

Cloud Deployment (Optional)

This repo is configured for cloud deployment to GCP Cloud Run via gapp. Deploying monarch-access as an HTTP MCP server means your Monarch session token stays on the server and is never exposed to clients — each client authenticates with a JWT issued by monarch-admin.

Runtime contract

The MCP server reads these environment variables at startup. gapp.yaml in this repo wires them up for Cloud Run; any other host must provide the same:

Variable Required Purpose
SIGNING_KEY yes JWT signing secret. Sourced from Google Secret Manager via gapp (generate: true). Retrieve later with gapp secret get.
APP_USERS_PATH yes for durable deploys Directory for per-user profiles. Must be a persistent path — gapp maps this to a mounted volume.
JWT_AUD no Expected JWT audience claim. Leave unset unless you're running multiple apps with a shared signing key.
TOKEN_DURATION_SECONDS no Lifetime of newly issued JWTs. Defaults to ~10 years.

The server serves the MCP endpoint at /, a liveness probe at /health, and admin REST endpoints under /admin/*.

Deploy

# Install gapp CLI
pipx install git+https://github.com/echomodel/gapp.git

# Attach a GCP project and deploy
gapp setup your-gcp-project-id
gapp deploy

Connect the admin CLI

Retrieve the generated signing key from Secret Manager and point the admin CLI at the deployed instance:

SIGNING_KEY=$(gapp secret get SIGNING_KEY --plaintext)
monarch-admin connect https://your-service-url --signing-key "$SIGNING_KEY"

connect persists the URL and signing key to ~/.config/monarch/setup.json, so subsequent monarch-admin commands don't need the flags repeated.

Verify the deployment

monarch-admin health

Register a user

monarch-admin users add user@example.com --token "$MONARCH_SESSION_TOKEN"

See Authentication for how to obtain $MONARCH_SESSION_TOKEN. To rotate a user's token, revoke and re-add:

monarch-admin users revoke user@example.com
monarch-admin users add user@example.com --token "$NEW_TOKEN"

Issue a JWT for an MCP client

monarch-admin tokens create user@example.com

Copy the returned token and register the remote server with your MCP client. Both Claude Code and Gemini CLI expand ${VAR} in MCP config, so keep the token in an env var rather than pasting it into config files:

export MONARCH_JWT="<token from tokens create>"

# Claude Code
claude mcp add --scope user --transport http monarch https://your-service-url/ \
  --header "Authorization: Bearer \${MONARCH_JWT}"

# Gemini CLI
gemini mcp add --transport http monarch https://your-service-url/ \
  --header "Authorization: Bearer \${MONARCH_JWT}"

See the gapp repo for deeper deployment documentation.

Development

See CONTRIBUTING.md for development setup, testing, and architecture.

For agents

If you are a coding agent operating this repo with plugin support, the author-mcp-app and mcp-app-admin skills provide step-by-step workflows for authoring and operating apps on the mcp-app framework. They are optional — this README and CONTRIBUTING.md are self-sufficient.

License

MIT