Metadata-Version: 2.4
Name: monarch-mcp
Version: 0.1.4
Summary: Model Context Protocol (MCP) server for Monarch Money personal finance platform
Author: vargahis
License-Expression: MIT
Project-URL: Homepage, https://github.com/vargahis/monarch-mcp
Project-URL: Repository, https://github.com/vargahis/monarch-mcp
Project-URL: Issues, https://github.com/vargahis/monarch-mcp/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Requires-Python: <3.14,>=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp<3.0.0,>=2.12.0
Requires-Dist: monarchmoneycommunity~=1.3.2
Requires-Dist: keyring>=24.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: asyncio>=3.4.3
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: pylint>=3.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

# Monarch Money MCP Server
<!-- mcp-name: io.github.vargahis/monarch-money -->

A Model Context Protocol (MCP) server for integrating with the Monarch Money personal finance platform through Claude Desktop.

## Overview

- **Secure by design** — browser-based login, token stored in OS keychain (never in config files or env vars)
- **Safe by default** — read-only mode prevents accidental changes; write tools require explicit opt-in
- **Comprehensive** — 44 tools covering accounts, transactions, splits, budgets, cashflow, tags, categories, transaction rules, recurring merchants, and credit history
- **Easy to install** — Claude Desktop extension (`.mcpb`), `uvx`, or `pip`

**Two operating modes:**

The server starts in **read-only mode** by default. Write tools are hidden and blocked until you explicitly opt in.

| | Read-only (default) | Write mode |
|---|---|---|
| **View** accounts, transactions, budgets | Yes | Yes |
| **Analyze** cashflow, spending, net worth | Yes | Yes |
| **Create** transactions, tags, categories, rules | No | Yes |
| **Update** accounts, budgets, splits | No | Yes |
| **Delete** transactions, tags, accounts | No | Yes |

## Quick Start

### Installation

#### Option 1: Claude Desktop Extension (.mcpb) — Recommended for Claude Desktop

> Enables toggling write mode on/off directly from the Claude Desktop app.

1. Download the latest `.mcpb` from [Releases](https://github.com/vargahis/monarch-mcp/releases)
2. In Claude Desktop: **Settings > Extensions > Advanced Settings > Install Extensions** — select the `.mcpb` file
3. Restart Claude Desktop

To enable write tools: **Settings > Extensions > Monarch Money MCP Server > Configure** — toggle **"Enable write tools"** and click **Save**.

---

#### Option 2: uvx (no install required) — Recommended for agents (e.g. Claude Code or Cursor)

> Also works with Claude Desktop, but write mode cannot be toggled from the app — set it in the config instead.

Add to your MCP config file:

```json
{
  "mcpServers": {
    "Monarch Money": {
      "command": "uvx",
      "args": ["monarch-mcp"]
    }
  }
}
```

To enable write tools:

```json
{
  "mcpServers": {
    "Monarch Money": {
      "command": "uvx",
      "args": ["monarch-mcp", "--enable-write"]
    }
  }
}
```

---

#### Option 3: pip install — Recommended for local installation and venv

```bash
pip install monarch-mcp
```

> **Contributors**: See [docs/releasing.md](docs/releasing.md) for the release process, version scheme, and pre-release testing via TestPyPI.

Add to your MCP config using the full path to your Python interpreter:

```json
{
  "mcpServers": {
    "Monarch Money": {
      "command": "/path/to/bin/python3",
      "args": ["-m", "monarch_mcp"]
    }
  }
}
```

To enable write tools, add `"--enable-write"` to `args`.

---

#### Option 4: Clone and install — Recommended for development

```bash
git clone https://github.com/vargahis/monarch-mcp.git
cd monarch-mcp
pip install -e .
```

Then add to your MCP config using the Python interpreter from your dev environment:

```json
{
  "mcpServers": {
    "Monarch Money": {
      "command": "/path/to/bin/python3",
      "args": ["-m", "monarch_mcp"]
    }
  }
}
```

To enable write tools, add `"--enable-write"` to `args`.

### Authentication

Authentication happens **automatically in your browser** the first time the MCP server starts without a saved session.

1. Start (or restart) Claude Desktop
2. The server detects that no token exists and opens a login page in your browser
3. Enter your Monarch Money email and password
4. Provide your 2FA code if you have MFA enabled
5. Once authenticated, the token is saved to your system keyring — you're all set

Key details:

- **Credentials are entered in your browser only** — never through Claude Desktop
- **Token stored in the OS keyring** — persists across restarts, lasts weeks/months
- **Expired sessions re-authenticate automatically** — the browser login re-triggers on the next tool call
- **MFA fully supported**
- **Fallback**: run `python login_setup.py` in a terminal for headless environments

For technical details on the auth architecture, see [docs/authentication.md](docs/authentication.md).

### Usage Examples

```
Show me all my financial accounts
```

```
What were my last 50 transactions?
```

```
How's my budget looking this month?
```

```
Analyze my cashflow for the last 3 months
```

```
Create a tag called "Business Expenses" in red
```

## Available Tools

| Tool | Description | Mode |
|------|-------------|------|
| **Auth** | | |
| `setup_authentication` | Get setup instructions | read |
| `check_auth_status` | Check authentication status | read |
| `debug_session_loading` | Debug keyring issues | read |
| **Accounts** | | |
| `get_accounts` | Get all financial accounts | read |
| `get_account_holdings` | Get investment holdings | read |
| `get_account_history` | Get historical balance data | read |
| `get_recent_account_balances` | Get daily balances | read |
| `get_account_snapshots_by_type` | Net worth by account type | read |
| `get_aggregate_snapshots` | Daily aggregate net value | read |
| `get_institutions` | Get connected institutions | read |
| `get_account_type_options` | Get valid account types | read |
| `refresh_accounts` | Request account data refresh | read |
| `create_manual_account` | Create manual account | write |
| `update_account` | Update account settings | write |
| `delete_account` | Delete an account | write |
| **Transactions** | | |
| `get_transactions` | Get transactions with filtering (date, account, category, tag, search, needs\_review, and more) | read |
| `get_transaction_details` | Get full transaction detail | read |
| `get_transactions_summary` | Aggregate transaction stats | read |
| `get_transaction_splits` | Get split information | read |
| `get_recurring_transactions` | Get recurring transactions | read |
| `find_merchant_id_by_name` | Search recent transactions for a merchant and return distinct IDs | read |
| `create_transaction` | Create new transaction | write |
| `update_transaction` | Update existing transaction (clear notes with `clear_notes`, unlink goal with `clear_goal`) | write |
| `delete_transaction` | Delete a transaction | write |
| `update_transaction_splits` | Create/modify/delete splits | write |
| `update_recurring_merchant` | Mark/unmark a merchant as recurring, update its frequency/amount, or deactivate it — `is_recurring` is required on every call (requires `--enable-write`) | write |
| **Tags** | | |
| `get_transaction_tags` | Get all tags | read |
| `create_transaction_tag` | Create new tag | write |
| `delete_transaction_tag` | Delete a tag | write |
| `set_transaction_tags` | Set tags on a transaction | write |
| **Categories** | | |
| `get_transaction_categories` | Get all categories | read |
| `get_transaction_category_groups` | Get category groups | read |
| `create_transaction_category` | Create a category | write |
| `delete_transaction_category` | Delete a category | write |
| **Rules** | | |
| `get_transaction_rules` | List every transaction rule with its criteria, actions, and recent application stats | read |
| `create_transaction_rule` | Create a transaction rule with full criteria + actions (category, tags, merchant, amount, splits…) | write |
| `update_transaction_rule` | Update a rule by id; merges overrides onto the current rule (handles Monarch's REPLACE semantics) | write |
| `delete_transaction_rule` | Delete a rule by ID | write |
| **Budgets & Cashflow** | | |
| `get_budgets` | Get budget information | read |
| `get_cashflow` | Get cashflow analysis | read |
| `get_cashflow_summary` | Get cashflow summary | read |
| `set_budget_amount` | Set budget for category | write |
| **Other** | | |
| `get_subscription_details` | Get subscription status | read |
| `get_credit_history` | Get credit score history | read |

## Testing

This project has two complementary test surfaces:

**1. Mocked unit tests (the quality gate)** — fast, offline, no Monarch connection. These run in CI
and must stay green:

```bash
uv run pytest tests/
```

The Monarch client is mocked, so these never touch a real account. Live e2e tests (below) are
deselected by default.

**2. Live end-to-end (e2e) integration tests** — exercise the MCP tools against a **real** Monarch
account to verify they handle the live API robustly (adversarial/edge inputs, server-side error
paths). They are opt-in and never run in CI:

```bash
MONARCH_LIVE_TESTS=1 uv run pytest tests/integration -m integration
```

Prerequisites: a stored keyring token (run `python login_setup.py` once), or `MONARCH_EMAIL` /
`MONARCH_PASSWORD` in the environment. Without these, the suite skips. The tests create and delete
data prefixed with `MCP-Test-` and self-clean (a post-suite sweep removes any residue). See
[`tests/integration/README.md`](tests/integration/README.md) for details and safety notes.

> There is also a separate **agent** test skill (`.claude/skills/test-monarch-mcp/`) that drives an
> AI agent to verify it *calls* the tools correctly — distinct from the two pytest suites above.

## 🙏 Acknowledgments

Forked from [@robcerda](https://github.com/robcerda)'s [monarch-mcp-server](https://github.com/robcerda/monarch-mcp-server), maintained by vargahis.

Built on the [monarchmoneycommunity](https://pypi.org/project/monarchmoneycommunity/) Python library. 

Thanks to:
- [@robcerda](https://github.com/robcerda) for the original MCP server
- [@hammem](https://github.com/hammem) for the original [monarchmoney](https://github.com/hammem/monarchmoney) library
- [@bradleyseanf](https://github.com/bradleyseanf) for the community fork

## License

MIT License
