Monarch Money Community

Python library for accessing Monarch Money data.

Installation

From Source Code

Clone this repository from Git

git clone https://github.com/bradleyseanf/monarchmoneycommunity.git

Via pip

pip install monarchmoneycommunity

Import the library as monarchmoney after installation.

This package pins gql to 4.0.

Instantiate & Login

There are two ways to use this library: interactive and non-interactive.

Interactive

If you're using this library in something like iPython or Jupyter, you can run an interactive-login which supports multi-factor authentication:

from monarchmoney import MonarchMoney

mm = MonarchMoney()
await mm.interactive_login()

This will prompt you for the email, password and, if needed, the multi-factor token.

Non-interactive

For a non-interactive session, you'll need to create an instance and login:

from monarchmoney import MonarchMoney

mm = MonarchMoney()
await mm.login(email, password)

This may throw a RequireMFAException. If it does, you'll need to get a multi-factor token and call the following method:

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
try:
        await mm.login(email, password)
except RequireMFAException:
        await mm.multi_factor_authenticate(email, password, multi_factor_code)

Alternatively, you can provide the MFA Secret Key. The MFA Secret Key is found when setting up the MFA in Monarch Money by going to Settings -> Security -> Enable MFA -> and copy the Two-factor text code. Then provide it in the login() method:

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
await mm.login(
        email=email,
        password=password,
        save_session=False,
        use_saved_session=False,
        mfa_secret_key=mfa_secret_key,
    )

Use a Saved Session

You can easily save your session for use later on. While we don't know precisely how long a session lasts, authors of this library have found it can last several months.

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
mm.interactive_login()

# Save it for later, no more need to login!
mm.save_session()

Once you've logged in, you can simply load the saved session to pick up where you left off.

from monarchmoney import MonarchMoney, RequireMFAException

mm = MonarchMoney()
mm.load_session()

# Then, start accessing data!
await mm.get_accounts()

Accessing Data

As of writing this README, the following methods are supported:

Non-Mutating Methods

Mutating Methods

Typed Client

If you want typed account, budget, subscription, and holdings models, import the typed client:

from typedmonarchmoney import TypedMonarchMoney

mm = TypedMonarchMoney()
accounts = await mm.get_accounts()

The typed client provides MonarchAccount, MonarchBudget, MonarchBudgetMonth, MonarchSubscription, MonarchCashflowSummary, and MonarchHoldings models.

Contributing

Any and all contributions - code, documentation, feature requests, feedback - are welcome!

If you plan to submit up a pull request, you can expect a timely review. There aren't any strict requirements around the environment you'll need.

Opening a pull request

This library requires a pre-push check requiring that you log into your Monarch account and test all NON-MUTATING methods return valid JSON data including those of new types. If any fail, the push fails.

# One-time setup
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
make install-hooks

# Automatically runs run_tests.py before pushing
git push

FAQ

How do I use this API if I login to Monarch via Google?

If you currently use Google or 'Continue with Google' to access your Monarch account, you'll need to set a password to leverage this API. You can set a password on your Monarch account by going to your security settings.

Don't forget to use a password unique to your Monarch account and to enable multi-factor authentication!

Projects Using This Library

Open a PR adjusting the README if you would like to be added to this list

Disclaimer: These projects are neither affiliated nor endorsed by Monarch Money.

• mmoney-cli - Access your MonarchMoney data via CLI
• monarchmoney-typed - MonarchMoney Home Assistant Integration
• monarch-mcp-server - Model Context Protocol (MCP) server for integrating with Monarch Money.