Monarch MCP Server

🚀 Monarch Money MCP Server

このサーバーは、Monarch Money個人金融プラットフォームと統合するためのModel Context Protocol (MCP) サーバーです。Claude Desktopを通じて、金融口座、取引、予算、分析情報にシームレスにアクセスできます。

私のMonarchMoneyリファラル: https://www.monarchmoney.com/referral/ufmn0r83yf?r_source=share

@hammemによるMonarchMoney Pythonライブラリを使用して構築 - MFAを完全にサポートする素晴らしい非公式のMonarch Money APIです。

🚀 クイックスタート

1. インストール

1. このリポジトリをクローンする:

   git clone https://github.com/robcerda/monarch-mcp-server.git
   cd monarch-mcp-server
   

2. 依存関係をインストールする:

   pip install -r requirements.txt
   pip install -e .
   

3. Claude Desktopを設定する: これをClaude Desktopの設定ファイルに追加します。

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "Monarch Money": {
         "command": "/opt/homebrew/bin/uv",
         "args": [
           "run",
           "--with",
           "mcp[cli]",
           "--with-editable",
           "/path/to/your/monarch-mcp-server",
           "mcp",
           "run",
           "/path/to/your/monarch-mcp-server/src/monarch_mcp_server/server.py"
         ]
       }
     }
   }
   

   重要: /path/to/your/monarch-mcp-server を実際のパスに置き換えてください！

4. Claude Desktopを再起動する

2. 一度限りの認証設定

重要: セキュリティとMFAサポートのため、認証はClaude Desktopの外部で行われます。

ターミナルを開き、以下を実行します。

cd /path/to/your/monarch-mcp-server
python login_setup.py

指示に従います。

• Monarch Moneyのメールアドレスとパスワードを入力します。
• MFAが有効になっている場合は、2FAコードを提供します。
• セッションは自動的に保存されます。

3. Claude Desktopでの使用開始

認証が完了したら、Claude Desktopで直接以下のツールを使用できます。

• get_accounts - すべての金融口座を表示します。
• get_transactions - フィルタリング機能付きの最近の取引を表示します。
• get_budgets - 予算情報と支出を表示します。
• get_cashflow - 収入/支出分析を表示します。

✨ 主な機能

📊 口座管理

• 口座の取得: 残高と金融機関の情報を含む、すべてのリンクされた金融口座を表示します。
• 口座の保有資産の取得: 投資口座の証券や投資を表示します。
• 口座の更新: 金融機関からのリアルタイムのデータ更新を要求します。

💰 取引アクセス

• 取引の取得: 日付、口座、ページネーションでフィルタリングした取引データを取得します。
• 取引の作成: 口座に新しい取引を追加します。
• 取引の更新: 既存の取引を変更します（金額、説明、カテゴリ、日付）。

📈 財務分析

• 予算の取得: 支出額と残高を含む予算情報にアクセスします。
• キャッシュフローの取得: 指定された日付範囲の財務キャッシュフローを収入/支出の内訳で分析します。

🔐 安全な認証

• 一度限りの設定: 一度認証すれば、数週間/数ヶ月使用できます。
• MFAサポート: 二要素認証を完全にサポートします。
• セッションの永続化: 頻繁に再認証する必要はありません。
• 安全: 資格情報はClaude Desktopを介して送信されません。

🛠️ 利用可能なツール

💻 使用例

基本的な使用法

get_accountsを使用して、すべての金融口座を表示します。

高度な使用法

get_transactionsを使用して、直近50件の取引を表示します。

📅 日付フォーマット

• すべての日付は YYYY-MM-DD 形式で指定する必要があります（例: "2024-01-15"）。
• 取引金額: 収入は正、支出は負です。

🔧 トラブルシューティング

認証問題

「Authentication needed」というエラーが表示された場合:

1. 設定コマンドを実行します: cd /path/to/your/monarch-mcp-server && python login_setup.py
2. Claude Desktopを再起動します。
3. get_accounts などのツールを使用してみます。

セッション期限切れ

セッションは数週間有効ですが、期限切れになった場合:

1. 同じ設定コマンドを再度実行します。
2. 資格情報と2FAコードを入力します。
3. セッションは自動的に更新されます。

一般的なエラーメッセージ

• "No valid session found": login_setup.py を実行します。
• "Invalid account ID": get_accounts を使用して有効な口座IDを確認します。
• "Date format error": 日付はYYYY-MM-DD形式で使用してください。

🏗️ 技術詳細

プロジェクト構造

monarch-mcp-server/
├── src/monarch_mcp_server/
│   ├── __init__.py
│   └── server.py          # メインサーバーの実装
├── login_setup.py         # 認証設定スクリプト
├── pyproject.toml         # プロジェクト設定
├── requirements.txt       # 依存関係
└── README.md             # このドキュメント

セッション管理

• セッションは .mm/mm_session.pickle に安全に保存されます。
• セッションの自動検出と読み込みが行われます。
• セッションはClaude Desktopの再起動を通じて保持されます。
• 頻繁な再認証は必要ありません。

セキュリティ機能

• 資格情報はClaude Desktopを介して送信されません。
• MFA/2FAが完全にサポートされています。
• セッションファイルは暗号化されています。
• 認証は安全なターミナル環境で処理されます。

🙏 謝辞

このMCPサーバーは、@hammemによって作成された優れたMonarchMoney Pythonライブラリをベースに構築されています。彼らのライブラリは、この統合を可能にする強力な基盤を提供しています。

• MFAサポート付きの安全な認証
• Monarch Moneyの包括的なAPIカバレッジ
• セッション管理と永続化
• 文書化され、保守されたコードベース

@hammemがこの重要なライブラリを作成し、保守してくれたことに感謝します！

📄 ライセンス

MITライセンス

🆘 サポート

問題が発生した場合は:

1. check_auth_status で認証を確認します。
2. 設定コマンドを再度実行します: cd /path/to/your/monarch-mcp-server && python login_setup.py
3. エラーログを確認して詳細なメッセージを確認します。
4. Monarch Moneyサービスがアクセス可能であることを確認します。

🔄 更新

サーバーを更新するには:

1. リポジトリから最新の変更を取得します。
2. Claude Desktopを再起動します。
3. 必要に応じて認証を再度実行します: python login_setup.py