Monarch MCP Server

Monarch Money MCP Server

AI アシスタントを使って、MCP 経由で Monarch Money の口座、取引、予算を読み取り、更新できます。

このフォークの特長

この FastMCP による書き換え版では、colvint のオリジナルサーバーに次のツールを追加しています。

• 検索と一括編集： search_transactions で加盟店やキーワードを検索できます。update_transactions_bulk では、項目ごとの結果を確認しながら取引を並行して編集できます。
• 支出分析： get_spending_summary でカテゴリ、口座、月ごとに合計を集計できます。analyze_spending_patterns で月ごとの比較を行えます。
• 1 回の呼び出しで全体を把握： get_complete_financial_overview で口座、予算、キャッシュフロー、取引、カテゴリをまとめて確認できます。
• 分割と定期スケジュール： 取引の分割内容の読み取りと置き換え、予定された発生分の確認、加盟店全体の定期設定の編集ができます。

オリジナル版や keithah の機能強化版 Python フォークとは異なり、このサーバーでは次の機能も提供しています。

• 型付きの結果： outputSchema を使った構造化出力と、テキスト形式のフォールバックを備えています。
• MCP リソースとプロンプト： 口座、カテゴリ、金融機関のリソース、口座ごとの保有資産・履歴テンプレート、引数の補完機能付きのガイド付きプロンプトを提供します。
• アシスタント向けの呼び出し： コンパクトな取引・カテゴリの記録、自然言語の日付、読み取り／書き込みラベル、一括分析の進行状況を提供します。

比較の確認日は 2026 年 9 月 14 日です。他のフォークも金融ツールの機能が一部重複しています。機能強化版 Python フォークは、より広範なライブラリ API を公開しています。このプロジェクトは、すべての API メソッドを公開するのではなく、分析ワークフローと MCP 連携に重点を置いています。ツール一覧をご覧ください。

セットアップ

uv をインストールし、MCP クライアントが uvx monarch-mcp-jamiew を実行するよう設定してください。Monarch のメールアドレスとパスワードに加えて、TOTP ベースの 2FA に必要な MFA シークレットが必要です。

これらの機能は 0.5.2 に含まれており、PyPI から利用できます。

標準設定

mcpServers 設定を使用するクライアントの場合：

{
  "mcpServers": {
    "monarch-money": {
      "command": "uvx",
      "args": ["monarch-mcp-jamiew"],
      "env": {
        "MONARCH_EMAIL": "[email protected]",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

claude mcp add monarch-money \
  -e [email protected] \
  -e MONARCH_PASSWORD=your-password \
  -e MONARCH_MFA_SECRET=your-mfa-secret-key \
  -- uvx monarch-mcp-jamiew

codex mcp add monarch-money \
  --env [email protected] \
  --env MONARCH_PASSWORD=your-password \
  --env MONARCH_MFA_SECRET=your-mfa-secret-key \
  -- uvx monarch-mcp-jamiew

[mcp_servers.monarch-money]
command = "uvx"
args = ["monarch-mcp-jamiew"]
env = { MONARCH_EMAIL = "[email protected]", MONARCH_PASSWORD = "your-password", MONARCH_MFA_SECRET = "your-mfa-secret-key" }

mcp_servers:
  monarch-money:
    command: uvx
    args: ["monarch-mcp-jamiew"]
    env:
      MONARCH_EMAIL: "[email protected]"
      MONARCH_PASSWORD: "your-password"
      MONARCH_MFA_SECRET: "your-mfa-secret-key"

git clone https://github.com/jamiew/monarch-mcp
cd monarch-mcp
uv sync --locked

{
  "mcpServers": {
    "monarch-money": {
      "command": "/abs/path/to/uv",
      "args": ["--directory", "/abs/path/to/monarch-mcp", "run", "python", "server.py"],
      "env": {
        "MONARCH_EMAIL": "[email protected]",
        "MONARCH_PASSWORD": "your-password",
        "MONARCH_MFA_SECRET": "your-mfa-secret-key"
      }
    }
  }
}

メモ

claude mcp addおよびcodex mcp addコマンドは、認証情報をシェルの履歴に保存する場合があります。これを避けるには、クライアントの設定を直接編集し、設定ファイルを保護してください。

MFA シークレットの取得

1. Monarch Money の設定に移動し、2FA を有効にします。
2. QR コードが表示されたら、「Can't scan?」または「Enter manually」を探します。
3. ローテーションする6桁のコードではなく、TOTP シークレットキーをコピーします。
4. これをMONARCH_MFA_SECRETとして使用します。

ツール

このサーバーは、次の29個のツールを公開します。

保留中の取引には is_pending=True、確定済みの取引には False を指定します。両方を対象にする場合は省略します。単一更新と一括更新では、get_household_members から取得した owner_user_id を指定できます。 空文字列を指定すると共有所有権が設定され、省略または null の場合は所有権が変更されません。 割り当てを行うと、継承された所有権は上書きされます。verbose=True を指定して ownedByUser を確認してください。 更新レスポンスには含まれません。

ルールはデフォルトで 1 ページあたり 25 件（最大 100 件）、履歴はデフォルトで 100 件（最大 1,000 件）です。 limit、offset、返された next_offset を使って続きを取得してください。total_count には一致するすべてのレコードが含まれます。 ルールの詳細は verbose=True で引き続き取得できます。

ルールでは、カテゴリ、店舗名、タグ、または確認ステータスを設定できます。また、レポートから取引を非表示にすることもできます。各ルールでは、店舗名、明細テキスト、または金額のいずれかを照合条件として指定する必要があります。条件に該当しないルールへの編集は Monarch に無視されます。

ルールを編集するとき、省略した項目は変更されません。値を消去するには、[] または "" を渡します。Monarch は編集のたびにルール全体を置き換えるため、サーバーは変更を含むルール全体を返します。これにより、所有者、目標、分割情報など、ツールでは編集できない設定が保持されます。

apply_to_existing_transactions=True を指定すると、一致する過去の取引も変更されます。元に戻すのが難しいため、まず search_transactions で一致する取引を確認してください。

概要と支出分析は、デフォルトではコンパクトな要約を返します。verbose=True を指定すると完全なセクションが返されます。詳細モードでも、取引サンプルはそれぞれ最大 500 件と 2,000 件に制限されます。合計が完全なものとして扱えるか判断する前に、batch_metadata.transactions_truncated を確認してください。null は、上流で件数を取得できなかったことを意味します。

定期取引

get_recurring_transactions(start_date, end_date) は、記録済みの履歴ではなく予測を返します。 日付は ISO 形式または自然言語で指定できます。日付を指定しない場合は今月が選択され、日付を 1 つだけ指定した場合は、その月から不足している範囲の境界が補われます。

発生項目には、ストリーム、口座、カテゴリ、および利用可能な場合は一致する transactionId が含まれます。isPast は支払い済みを意味しません。記録済みの取引には get_transactions(is_recurring=True) を使用し、予測と記録済みの一致項目を二重に数えないでください。

update_recurring_transaction は、個別の発生項目ではなく、加盟店全体のスケジュールを変更します。stream.id や transactionId ではなく stream.merchant.id を使用し、名前が変更されないよう現在の加盟店名を指定してください。変更する設定のみを渡します：frequency、base_date、amount、is_recurring、または is_active。省略した設定は変更されません。Monarch の頻度と符号付き金額を使用してください。この操作では、サブスクリプションの解約、送金、記録済み取引の作成は行われません。

取引の形式

get_transactions と search_transactions は、デフォルトで簡潔なレコードを返します：

{
  "id": "txn_123",
  "date": "2025-03-15",
  "amount": -12.50,
  "merchant": "Corner Deli",
  "plaidName": "CORNER DELI NYC",
  "category": "Restaurants & Bars",
  "categoryId": "cat_001",
  "account": "Main Credit Card",
  "needsReview": true
}

pending は true の場合のみ表示され、notes は空でない場合のみ表示されます。取引の詳細をすべて取得するには get_transactions または search_transactions で、カテゴリの詳細をすべて取得するには get_transaction_categories で verbose=True を設定してください。

セッション管理

セッションは、次回以降のログインを高速化するために ~/.monarch-mcp/ にキャッシュされます（場所は MONARCH_SESSION_DIR 環境変数で変更できます）。認証に問題が発生した場合：

• キャッシュされたセッションを消去するには、~/.monarch-mcp/session.pickle を削除します
• 新たにログインするには、環境設定で MONARCH_FORCE_LOGIN=true を設定します
• システムクロックが正確であることを確認します（TOTP に必要です）

開発

ローカルセットアップ

実際の環境でチェックを行う場合は、.env ファイル（Git の追跡対象外）を作成し、uv --env-file で明示的に読み込みます：

MONARCH_EMAIL="[email protected]"
MONARCH_PASSWORD="your-password"
MONARCH_MFA_SECRET="YOUR_TOTP_SECRET_KEY"

テスト

uv run pytest tests/ -v                          # offline; live tests are skipped
MONARCH_RUN_INTEGRATION=true uv run --env-file .env pytest tests/test_integration.py -v
uv run --env-file .env scripts/health_check.py    # live API connectivity check

統合テストでは、MFA の再利用とログインのスロットリングを避けるため、1 回の新しいログインを共有します。テストが .env を自ら読み込んだり、保存済みセッションを読み書きしたりすることはありません。

CI チェック

CI と同じチェックを実行します：

uv run python scripts/ci.py

リリース

/release を使用して pyproject.toml のバージョンを更新し、コミットして vX.Y.Z のタグを付け、プッシュして GitHub リリースを作成します。公開ワークフロー は OIDC を通じて PyPI と MCP Registry に公開し、タグから server.json のバージョンを設定します。

ログ分析

ツール呼び出し回数と出力サイズを測定します：

uv run scripts/analyze_logs.py                    # full report
uv run scripts/analyze_logs.py --json             # JSON output
uv run scripts/eval_session.py snapshot           # mark log position
# ... use tools in Claude ...
uv run scripts/eval_session.py analyze            # analyze new entries

セキュリティ

警告： このサーバーは、Monarch Money API への非公式なアクセスを使用します。認証情報により、書き込みを含むアカウントへの完全なアクセスが可能になります。

• サーバーはローカルで実行され、要求された財務データを MCP クライアントに返します。クライアントのプライバシー設定とツールの承認を確認してください。
• パスワードと MFA シークレットを保護してください。TOTP シークレットがあれば、継続的にコードを生成できます。
• ~/.monarch-mcp/ 内のセッションファイルには認証トークンが含まれています。これらと、カスタムの MONARCH_SESSION_DIR を保護してください。
• ログには財務情報の入力値やエラーの詳細が含まれる場合があります。共有する前に確認してください。
• 認証情報を含む .env、.mcp.json、クライアント設定ファイルは、決してコミットしないでください。
• Monarch Money は、非公式 API へのアクセスをいつでも変更または制限する可能性があります。

クレジット

colvint/monarch-money-mcp からフォークしました。API アクセスには bradleyseanf/monarchmoneycommunity を使用しています。これは hammem/monarchmoney を基にしています。ソースからインストールする場合はコミットを固定し、PyPI からインストールする場合は公開済みのライブラリを使用します。

貢献者： @caseypugh（取引の分割）、@seanperkins（支出サマリーのページネーション）、@rajatbhagat（セットアップドキュメント）、@samyk（取引ルール）、@prerak-proof（取引の詳細）。