Avie Money Lover MCP / ローカルブリッジ

非公式の Money Lover 連携ツール。2つのワークフローに対応しています。

1. MCP サーバー — Money Lover の読み書きツールを MCP 対応クライアントに公開します。

2. GPT + ローカルブリッジ — ChatGPT に明細 JSON の作成・レビューを任せ、Money Lover のトークン/クッキーは自分のマシンに保持したまま最終的なインポートを実行します。

非公式プロジェクトです。 このリポジトリは Money Lover とは提携・承認・支援関係にありません。Money Lover の Web アプリで観測された Web エンドポイントを使用しています。これらのエンドポイント、認証フロー、カテゴリの動作、およびアンチボット要件は予告なく変更される可能性があります。

できること

• 認証済みユーザー情報の取得

• ウォレットとウォレットカテゴリの一覧表示

• 日付範囲による取引の読み取り

• 取引履歴を使用した Money Lover の user_category_v2 ソース ID からランタイム ID への解決

• 書き込みを行わない単一取引のプレビュー

• 重複保護付きの取引追加

• 銀行/カード明細バッチのプレビュー

• 明細合計に対する支出 − 収入の照合

• 完全重複、類似重複、未解決カテゴリ、レビュー行のフラグ付け

• 明示的な確認後のみ順次インポート

• 読み戻しによる作成取引の検証

• 部分インポート後の安全な再実行: 完全重複はスキップされます

Related MCP server: monarch-mcp

要件

• Windows 10/11、macOS、または Linux

• Node.js 22 以上

• 自分が管理する Money Lover アカウント

• 信頼性の高い書き込みに必要なもの: 新しい ウォレット所有者 セッション、必要な場合の現在のブラウザクッキー/cf_clearance、および対応するブラウザの User-Agent

クイックスタート

git clone https://github.com/haonguyen97ftu/avie-moneylover-mcp.git
cd avie-moneylover-mcp
npm install
npm test

Windows ヘルパーセットアップ

scripts\setup-windows.cmd

現在のシェルでのみ資格情報を設定します:

set "MONEYLOVER_ACCESS_TOKEN=YOUR_FRESH_OWNER_TOKEN"
set "MONEYLOVER_CF_CLEARANCE=YOUR_CURRENT_CF_CLEARANCE_VALUE"
set "MONEYLOVER_USER_AGENT=YOUR_EXACT_BROWSER_USER_AGENT"

次に実行します:

scripts\doctor.cmd

推奨される GPT + ローカルワークフロー

Bank/card statement
        ↓
ChatGPT extracts + categorizes
        ↓
statement JSON
        ↓
local preview
        ↓
review / duplicate / reconciliation checks
        ↓
explicit IMPORT confirmation
        ↓
Money Lover
        ↓
local verification report

Money Lover のトークン、リフレッシュトークン、パスワード、ブラウザクッキー、または cf_clearance を ChatGPT、GitHub の issue、ログ、スクリーンショットに貼り付けないでください。ChatGPT に必要なのは明細と生成されたプレビュー/結果 JSON のみです。

明細のプレビュー

scripts\preview.cmd data\your-statement.json

レビュー後のインポート

scripts\import.cmd data\your-statement.json

インポーターでは、書き込みが開始される前に正確に次のように入力する必要があります:

IMPORT

完全なベトナム語ガイドは docs/HUONG_DAN_SU_DUNG.md を参照してください。

確認された API の動作

認証済みリクエストは現在次のものを使用します:

Authorization: AuthJWT <access_token>

確認されたエンドポイント:

書き込みにはブラウザに似たヘッダーと現在の Cloudflare セッションが必要な場合があります。サポートされている環境変数は次のとおりです:

• MONEYLOVER_ACCESS_TOKEN

• MONEYLOVER_CF_CLEARANCE

• MONEYLOVER_COOKIE

• MONEYLOVER_USER_AGENT

• MONEYLOVER_TIMEOUT_MS

• MONEYLOVER_CATEGORY_LOOKBACK_DAYS

• MONEYLOVER_WRITE_DELAY_MS

バッチ明細の形式

data/example-statement.json から始めてください。完全なフィールドドキュメントは docs/STATEMENT_FORMAT.md にあります。

プレビュー:

npm run preview -- data\your-statement.json

インポート:

npm run import -- data\your-statement.json

オプションフラグ:

• --allow-review — 確認後に意図的に review に残した行を含めます

• --allow-mismatch — 明細照合保護をバイパスします。差異を理解している場合にのみ使用してください

• --allow-shared-wallet — 所有者の安全チェックをバイパスします。共有ウォレットへの書き込みは依然として失敗する可能性があります

• --confirm IMPORT — 非対話型の確認。通常の手動使用には推奨されません

安全のデフォルト

インポーターは次の場合に書き込みを拒否します:

• いずれかの行が blocked の場合

• --allow-review が指定されていないのに review 行が存在する場合

• --allow-mismatch が指定されていないのに明細照合の差がゼロ以外の場合

• --allow-shared-wallet が指定されていないのに認証済みユーザーがウォレット所有者でない場合

• 確認が正確に IMPORT でない場合

金額は正の数である必要があります。

カテゴリ v2

一部のアカウントでは /category/list からソース/テンプレートカテゴリ ID が公開されますが、/transaction/add は異なるランタイムカテゴリ ID を期待します。ブリッジは既存の取引からこのマッピングを学習します。

カテゴリが履歴に一度も出現していない場合は、次をコピーします:

config/runtime-category-overrides.example.json

を:

config/runtime-category-overrides.json

にコピーし、実際のブラウザの取引リクエストから観測されたランタイム ID を追加します。ローカルのオーバーライドファイルは Git によって無視されます。

公開リポジトリの安全性

このリポジトリは、ローカルの財務データがデフォルトでコミットされないように構成されています:

• data/*.json はサニタイズされた例を除き無視されます

• out/ は無視されます

• .env* は無視されます

• ローカルのランタイムカテゴリオーバーライドは無視されます

• ローカルのセッションヘルパーファイルは無視されます

プッシュする前に、次を実行してください:

npm run repo:check
npm test

その後、git status を手動で確認してください。

セキュリティ

トークン、パスワード、リフレッシュトークン、ブラウザクッキー、または cf_clearance の値が公開された場合は、漏洩したものとして扱い、セッションをローテーション/失効させてください。SECURITY.md を参照してください。

コントリビューション

バグ報告とプルリクエストを歓迎します。変更を送信する前に CONTRIBUTING.md をお読みください。実際の財務明細、アカウント識別子、トークン、またはクッキーを issue やテストフィクスチャに含めないでください。

ドキュメント

• ベトナム語使用ガイド

• 明細 JSON 形式

• アーキテクチャ

• GitHub 公開ガイド

• セキュリティポリシー

• 変更履歴

• GPT 明細正規化プロンプト

• GPT プレビューレビュープロンプト

ライセンス

MIT — LICENSE を参照してください。