Metadata-Version: 2.5
Name: monarch-money-mcp-cli
Version: 0.1.2
Summary: Read-only Monarch Money MCP server and CLI. Pull accounts, transactions, cash flow, spending and income into Claude or your terminal. Zero dependencies, token in the macOS Keychain.
Project-URL: Homepage, https://github.com/simplemind-dev/monarch-money-mcp-cli
Project-URL: Issues, https://github.com/simplemind-dev/monarch-money-mcp-cli/issues
Project-URL: Changelog, https://github.com/simplemind-dev/monarch-money-mcp-cli/blob/main/CHANGELOG.md
Author: simplemind
License-Expression: MIT
License-File: LICENSE
Keywords: budget,budgeting,claude,claude-code,cli,keychain,mcp,mcp-server,model-context-protocol,monarch,monarch-money,personal-finance
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: MacOS
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Provides-Extra: mcp
Requires-Dist: mcp==2.2.0; extra == 'mcp'
Description-Content-Type: text/markdown

# Monarch Money MCP server + CLI

A read-only MCP server and command line tool for [Monarch Money](https://www.monarch.com). Use it to give
Claude (or any MCP client) access to your accounts, transactions, cash flow, spending, income, budgets,
goals, recurring bills, investment holdings, and net worth.
There are no third-party dependencies beyond the MCP SDK, and your session token stays in the macOS Keychain.

> **Unofficial.** This project isn't affiliated with Monarch Money, Inc. It uses Monarch's private web API,
> which may change without notice.

## Quick start

Requires macOS, Python 3.11+, and [uv](https://docs.astral.sh/uv/).

```bash
uv tool install 'monarch-money-mcp-cli[mcp]'
monarch auth                                              # email, password, MFA code
monarch doctor                                            # everything should be ok
claude mcp add monarch -s user -- "$(which monarch)" mcp  # then restart Claude Code
```

Or with pipx: `pipx install 'monarch-money-mcp-cli[mcp]'`.

To upgrade: `uv tool upgrade monarch-money-mcp-cli` (or `pipx upgrade monarch-money-mcp-cli`), then restart Claude Code.

## Commands

```bash
monarch auth [login|status|logout|paste-token]
monarch doctor
monarch entities
monarch accounts list [--all]
monarch tx [--search TEXT] [--account ID] [--tag NAME] [--limit N]
monarch cashflow [--by-entity]
monarch spending
monarch income
monarch budgets
monarch goals [--all]
monarch recurring
monarch holdings [--account ID]
monarch networth [--daily]
```

- **Dates:** the default is the current month. Give `START END` (`YYYY-MM-DD`), or one of `--month YYYY-MM`,
  `--year YYYY`, `--ytd`, `--last-month`, `--days N`, or `--from DATE [--to DATE]`.
  `networth` defaults to the last 12 months; `holdings` shows current positions and takes no dates.
- **Business entities:** add `--entity <id|name|household>` to limit results to an entity. You can repeat it.
  It works on `accounts`, `tx`, `cashflow`, `spending`, and `income`.
- **Output:** `--output table|csv|json` (`--json` for short).

```bash
monarch spending --last-month
monarch cashflow --ytd --entity "Acme LLC"
monarch tx --from 2026-01-01 --output csv > transactions.csv
```

Run `monarch <command> --help` for all options.

## MCP server

**Claude Desktop:** add this to `~/Library/Application Support/Claude/claude_desktop_config.json`, using
the path that `which monarch` prints, then restart the app:

```json
{ "mcpServers": { "monarch": { "command": "/Users/you/.local/bin/monarch", "args": ["mcp"] } } }
```

The tools are all read-only: `monarch_list_entities`, `monarch_list_accounts`, `monarch_list_transactions`,
`monarch_cashflow_summary`, `monarch_cashflow_by_entity`, `monarch_spending_by_category`,
`monarch_income_by_category`, `monarch_budget_summary`, `monarch_list_goals`, `monarch_list_recurring`,
`monarch_list_holdings`, and `monarch_net_worth_history`.

## Troubleshooting

Run `monarch doctor`. Every row that isn't `ok` explains the problem, and most include the fix command.

- **Not logged in or session expired:** run `monarch auth`. If login asks for a CAPTCHA, use `monarch auth paste-token`.
- **Monarch is temporarily unavailable:** Monarch is down or overloaded. Wait a minute and try again.
- **`/mcp` doesn't show `monarch`:** restart Claude Code after adding the server.
- **Stale `monarch` entry pointing at `api.monarch.com/mcp`:** run the `claude mcp remove` command that `doctor` shows.

## Security

Your password is never stored. The tool only talks to `api.monarch.com` and never changes your data.
See [SECURITY.md](SECURITY.md).

## Development

```bash
git clone https://github.com/simplemind-dev/monarch-money-mcp-cli && cd monarch-money-mcp-cli
uv venv && uv pip install -e '.[mcp]'
uv run --no-project -- python -m unittest discover -s tests -v
```

## License

[MIT](LICENSE)
