Content
# Monarch Money MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes your [Monarch Money](https://www.monarchmoney.com/) personal finance data as tools for AI assistants like Claude.
Query your accounts, transactions, budgets, cashflow, investments, recurring bills, and receipts — all from your AI assistant.
## Features
- **17 MCP tools** covering accounts, transactions, budgets, cashflow, investments, recurring transactions, receipts, and more
- **SQLite caching** with configurable TTL (default 24h) — fast responses without hammering the API
- **Receipt/attachment downloading** — pull receipt images and PDFs to local storage
- **Read-only by design** — only exposes `get_*` methods, no writes to your financial data
- **Session-based auth** — login once, session persists across server restarts
## Tools
| Tool | Description |
|------|-------------|
| `get_accounts` | All linked accounts with balances and institution names |
| `get_account_holdings` | Investment positions for a brokerage account |
| `get_account_history` | Daily balance history for an account |
| `refresh_accounts` | Trigger a sync from financial institutions |
| `get_transactions` | Query transactions with filters (date, category, account, search, tags) |
| `get_transaction_details` | Full details for a single transaction (splits, attachments) |
| `get_transaction_categories` | All configured categories and groups |
| `get_transaction_tags` | All configured tags |
| `get_budgets` | Budget vs actual amounts by category |
| `get_cashflow` | Income/expense breakdown by category and merchant |
| `get_cashflow_summary` | Aggregated income, expenses, savings, savings rate |
| `get_recurring_transactions` | Bills, subscriptions, and recurring income |
| `download_transaction_receipt` | Download receipt/attachment files for a transaction |
| `list_receipts` | List all locally downloaded receipts |
| `get_institutions` | All linked financial institutions |
| `get_subscription_details` | Monarch Money subscription status |
| `clear_cache` | Clear cached data (all or by namespace) |
## Prerequisites
- Python 3.10+
- A [Monarch Money](https://www.monarchmoney.com/) account
## Installation
```bash
git clone https://github.com/felixgalindo/monarch-money-mcp.git
cd monarch-money-mcp
pip install -e .
```
Or with `uv`:
```bash
uv pip install -e .
```
## Setup
### 1. Configure credentials (email/password users)
```bash
cp .env.example .env
# Edit .env with your Monarch Money email and password
```
> **Signed up with Google or Apple?** You have two options:
>
> **Option A (recommended):** Add a password to your Monarch Money account so you can use email/password login:
> 1. Log in to [app.monarchmoney.com](https://app.monarchmoney.com) with Google/Apple
> 2. Go to **Settings > Security**
> 3. Click **Set Password** and create a password
> 4. Use your email + new password in the `.env` file or during login
>
> **Option B:** Use the session token method — the login script supports direct token entry. See step 2.
### 2. Authenticate
```bash
python -m monarch_money_mcp.login
```
You'll be prompted to choose your authentication method:
- **Option 1: Email/password** — enter your Monarch Money credentials (supports MFA)
- **Option 2: Session token** — for Google/Apple SSO users who can't use email/password login. The script walks you through extracting your token from the browser's Developer Tools.
You only need to do this once — the session token is stored securely in your OS keyring (macOS Keychain, Windows Credential Locker, or Linux Secret Service).
### 3. Configure your MCP client
#### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"monarch-money": {
"command": "python",
"args": ["-m", "monarch_money_mcp"],
"cwd": "/path/to/monarch-money-mcp"
}
}
}
```
#### Claude Code
Add to your Claude Code MCP settings:
```json
{
"mcpServers": {
"monarch-money": {
"command": "python",
"args": ["-m", "monarch_money_mcp"],
"cwd": "/path/to/monarch-money-mcp"
}
}
}
```
## Configuration
Environment variables (set in `.env`):
| Variable | Description | Default |
|----------|-------------|---------|
| `MONARCH_EMAIL` | Monarch Money email | _(required for login)_ |
| `MONARCH_PASSWORD` | Monarch Money password | _(required for login)_ |
| `MONARCH_MFA_SECRET` | TOTP secret for MFA (base32) | _(optional)_ |
| `CACHE_TTL_HOURS` | Cache time-to-live in hours | `24` |
| `DATA_DIR` | Directory for cache, sessions, receipts | `./data` |
## Project Structure
```
monarch-money-mcp/
├── src/monarch_money_mcp/
│ ├── server.py # MCP server — tool definitions
│ ├── cache.py # SQLite cache layer
│ ├── client.py # MonarchMoney client wrapper
│ ├── receipts.py # Receipt download/management
│ ├── login.py # Interactive authentication
│ └── config.py # Configuration and paths
├── data/ # Runtime data (gitignored)
│ ├── cache.db # SQLite cache
│ ├── session/ # Auth session token
│ └── receipts/ # Downloaded receipt files
└── pyproject.toml
```
## Security
- **Credentials are never stored in code or committed to git** — `.env` and `data/` are gitignored
- **Session tokens are stored locally** in `data/session/` as pickle files
- **All API traffic uses HTTPS** to Monarch Money's official endpoints only
- **No data is sent to third parties** — this server only communicates with `api.monarchmoney.com`
## Credits
- Built on the [monarchmoney](https://github.com/hammem/monarchmoney) Python library by [@hammem](https://github.com/hammem)
- Uses the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
## Author
**Felix Galindo** — [GitHub](https://github.com/felixgalindo)
## License
[MIT](LICENSE)
