Monarch MCP

Monarch Money MCP Server

Claude Desktop を通じて Monarch Money の個人向け財務プラットフォームと連携する Model Context Protocol（MCP）サーバーです。

概要

• セキュリティを重視した設計 — ブラウザーでログインし、トークンは OS のキーチェーンに保存されます（設定ファイルや環境変数には保存されません）
• デフォルトで安全 — 読み取り専用モードで誤った変更を防止します。書き込みツールを使うには明示的なオプトインが必要です
• 包括的 — アカウント、取引、分割、予算、キャッシュフロー、タグ、カテゴリ、取引ルール、定期的な加盟店、信用履歴をカバーする 44 個のツールを備えています
• 簡単にインストール可能 — Claude Desktop 拡張機能（.mcpb）、uvx、または pip

2 つの動作モード：

サーバーはデフォルトで読み取り専用モードで起動します。明示的にオプトインするまで、書き込みツールは非表示になり、ブロックされます。

	読み取り専用（デフォルト）	書き込みモード
表示 アカウント、取引、予算	はい	はい
分析 キャッシュフロー、支出、純資産	はい	はい
作成 取引、タグ、カテゴリ、ルール	いいえ	はい
更新 アカウント、予算、分割	いいえ	はい
削除 取引、タグ、アカウント	いいえ	はい

クイックスタート

インストール

オプション 1：Claude Desktop 拡張機能（.mcpb）— Claude Desktop での利用におすすめ

Claude Desktop アプリから書き込みモードを直接切り替えられます。

1. 最新の .mcpb を Releases からダウンロードします
2. Claude Desktop で、Settings > Extensions > Advanced Settings > Install Extensions を選択し、.mcpb ファイルを指定します
3. Claude Desktop を再起動します

書き込みツールを有効にするには、Settings > Extensions > Monarch Money MCP Server > Configure に移動し、"Enable write tools" を切り替えて Save をクリックします。

---

オプション 2：uvx（インストール不要）— エージェント（例：Claude Code や Cursor）での利用におすすめ

Claude Desktop でも動作しますが、アプリから書き込みモードを切り替えることはできません。代わりに設定で指定してください。

MCP 設定ファイルに追加します：

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

書き込みツールを有効にするには：

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

---

オプション 3：pip install — ローカルインストールや venv での利用におすすめ

pip install monarch-mcp

コントリビューターの方へ：リリース手順、バージョン体系、TestPyPI を使ったリリース前テストについては、docs/releasing.md を参照してください。

Python インタープリターのフルパスを使って、MCP 設定に追加します：

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

書き込みツールを有効にするには、args に "--enable-write" を追加します。

---

オプション 4：クローンしてインストール — 開発におすすめ

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

次に、開発環境の Python インタープリターを使って、MCP 設定に追加します：

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

書き込みツールを有効にするには、args に "--enable-write" を追加します。

認証

保存済みのセッションがない状態で MCP サーバーを初めて起動すると、ブラウザーで自動的に認証が行われます。

1. Claude Desktop を起動（または再起動）します
2. サーバーがトークンが存在しないことを検出し、ブラウザーでログインページを開きます
3. Monarch Money のメールアドレスとパスワードを入力します
4. MFA が有効な場合は、2FA コードを入力します
5. 認証が完了すると、トークンがシステムのキーチェーンに保存されます。これで準備完了です

主なポイント：

• 認証情報の入力はブラウザーのみです — Claude Desktop 経由で入力することはありません
• トークンは OS のキーチェーンに保存されます — 再起動後も保持され、数週間から数か月有効です
• セッションの有効期限が切れると自動的に再認証されます — 次にツールを呼び出すと、ブラウザーでのログインが再度開始されます
• MFA に完全対応
• 代替手段：ヘッドレス環境では、ターミナルで python login_setup.py を実行します

認証アーキテクチャの技術的な詳細については、docs/authentication.md を参照してください。

使用例

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

利用可能なツール

ツール	説明	モード
認証
setup_authentication	セットアップ手順を取得	読み取り
check_auth_status	認証ステータスを確認	読み取り
debug_session_loading	キーリングの問題をデバッグ	読み取り
口座
get_accounts	すべての金融口座を取得	読み取り
get_account_holdings	投資保有資産を取得	読み取り
get_account_history	過去の残高データを取得	読み取り
get_recent_account_balances	日次残高を取得	読み取り
get_account_snapshots_by_type	口座種別ごとの純資産を取得	読み取り
get_aggregate_snapshots	日次の集計純資産額を取得	読み取り
get_institutions	接続済みの金融機関を取得	読み取り
get_account_type_options	有効な口座種別を取得	読み取り
refresh_accounts	口座データの更新をリクエスト	読み取り
create_manual_account	手動で口座を作成	書き込み
update_account	口座設定を更新	書き込み
delete_account	口座を削除	書き込み
取引
get_transactions	絞り込み条件（日時、口座、カテゴリ、タグ、検索、needs_review など）を指定して取引を取得	読み取り
get_transaction_details	取引の詳細全体を取得	読み取り
get_transactions_summary	取引統計を集計	読み取り
get_transaction_splits	分割情報を取得	読み取り
get_recurring_transactions	定期取引を取得	読み取り
find_merchant_id_by_name	最近の取引から加盟店を検索し、一意のIDを返す	読み取り
create_transaction	新しい取引を作成	書き込み
update_transaction	既存の取引を更新（clear_notes でメモを消去、clear_goal で目標との紐付けを解除）	書き込み
delete_transaction	取引を削除	書き込み
update_transaction_splits	分割を作成・変更・削除	書き込み
update_recurring_merchant	加盟店を定期取引としてマーク、またはマーク解除し、頻度や金額を更新するか、無効化します。毎回の呼び出しで is_recurring が必須です（--enable-write が必要）	書き込み
タグ
get_transaction_tags	すべてのタグを取得	読み取り
create_transaction_tag	新しいタグを作成	書き込み
delete_transaction_tag	タグを削除	書き込み
set_transaction_tags	取引にタグを設定	書き込み
カテゴリ
get_transaction_categories	すべてのカテゴリを取得	読み取り
get_transaction_category_groups	カテゴリグループを取得	読み取り
create_transaction_category	カテゴリを作成	書き込み
delete_transaction_category	カテゴリを削除	書き込み
ルール
get_transaction_rules	条件、アクション、最近の適用統計を含むすべての取引ルールを一覧表示	読み取り
create_transaction_rule	条件とアクション（カテゴリ、タグ、加盟店、金額、分割など）をすべて指定して取引ルールを作成	書き込み
update_transaction_rule	IDでルールを更新。現在のルールに上書き内容を統合します（Monarch の REPLACE セマンティクスに対応）	書き込み
delete_transaction_rule	IDでルールを削除	書き込み
予算とキャッシュフロー
get_budgets	予算情報を取得	読み取り
get_cashflow	キャッシュフロー分析を取得	読み取り
get_cashflow_summary	キャッシュフローの概要を取得	読み取り
set_budget_amount	カテゴリの予算を設定	書き込み
その他
get_subscription_details	サブスクリプションのステータスを取得	読み取り
get_credit_history	クレジットスコアの履歴を取得	読み取り

テスト

このプロジェクトには、相互に補完する2種類のテストがあります。

1. モックを使用したユニットテスト（品質ゲート） — 高速で、オフラインで実行でき、Monarch への接続は不要です。これらは CI で実行され、常に成功する状態を保つ必要があります。

uv run pytest tests/

Monarch クライアントはモック化されているため、実際のアカウントにアクセスすることはありません。ライブ e2e テスト（以下を参照）は、デフォルトで選択解除されています。

2. ライブのエンドツーエンド（e2e）統合テスト — 実際の Monarch アカウントに対して MCP ツールを実行し、ライブ API に堅牢に対応できることを検証します（敵対的な入力やエッジケースの入力、サーバー側のエラー経路など）。これらはオプトイン方式で、CI では実行されません。

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

前提条件：保存済みのキーチェーントークン（python login_setup.py を一度実行する）か、環境変数 MONARCH_EMAIL／MONARCH_PASSWORD が必要です。どちらもない場合、テストスイートはスキップされます。テストでは MCP-Test- をプレフィックスにしたデータを作成・削除し、後処理で自己クリーンアップします（テストスイート実行後の一括処理で残ったデータを削除します）。詳細と安全に関する注意事項については、tests/integration/README.md を参照してください。

これらとは別に、独立したエージェントテストスキル（.claude/skills/test-monarch-mcp/）もあります。このスキルは、AI エージェントにツールを正しく「呼び出す」ことを検証させます。上記の2つの pytest テストスイートとは別のものです。

🙏 謝辞

@robcerda の monarch-mcp-server からフォークし、vargahis が保守しています。

monarchmoneycommunity Python ライブラリを基盤としています。

以下の方々に感謝します。

• オリジナルの MCP サーバーを提供してくださった @robcerda
• オリジナルの monarchmoney ライブラリを提供してくださった @hammem
• コミュニティフォークを提供してくださった @bradleyseanf

ライセンス

MIT License