Personal Finance MCP

personal-finance-mcp

非公式です。 このプロジェクトは Plaid Inc. と提携、推奨、または後援関係にありません。「Plaid」は Plaid Inc. の商標です。これは、お客様が提供する認証情報を使用して Plaid の API と通信するセルフホスト型クライアントです。

銀行口座、クレジットカード、ローン、証券口座を（Plaid 経由で）Claude Code のような MCP クライアントに接続する、セルフホスト可能な読み取り専用 MCP サーバーです。第三者のアグリゲーター（Monarch、Mint など）を介さず、自然な英語でご自身の財務状況について質問できます。

質問できること

• 「すべての口座の合計残高はいくらですか？」
• 「過去 30 日間に 100 ドルを超えた取引を表示してください。」
• 「まだ支払いを続けているサブスクリプションはどれですか？」
• 「先月、食料品にいくら使いましたか？」
• 「再認証が必要な銀行はありますか？」

セッション例（説明用）：

you    : What did I spend on groceries last month?
claude : [calls get_transactions]
         $487.23 across 14 transactions. Top merchants:
         Whole Foods ($198), Trader Joe's ($156), Safeway ($89).

you    : Any subscriptions I'm still paying for?
claude : [calls get_recurring_transactions]
         7 active recurring outflows totaling $142/mo:
         Netflix ($15.99), Spotify ($11.99), NYT ($4), ...

ツール

9 つのツールはすべて読み取り専用です。各ツールは {<data>: [...], "warnings": [...]} を返すため、1 つの銀行で問題が起きてもクエリ全体には影響しません。

ツール	内容
list_accounts	残高を含む、リンク済みのすべての銀行のすべての口座
get_balances	現在残高と利用可能残高をリアルタイムで取得（口座による絞り込みは任意）
get_transactions	指定期間内の取引（最長 2 年前まで）
search_transactions	加盟店名／名称／取引相手を横断したキーワード検索
get_recurring_transactions	検出された定期的な入金および出金の明細
get_liabilities	APR と支払い詳細を含む、クレジットカード、学生ローン、住宅ローン
get_investment_holdings	銘柄記号と証券メタデータを含む現在の保有資産
get_investment_transactions	指定期間内の購入／売却／配当履歴
get_institutions_status	リンク済みの各銀行の状態（再認証の必要性を表示）

クイックスタート

Python 3.11 以降、Plaid アカウント（無料の Trial プラン）、MCP クライアントが必要です。

1. Plaid のセットアップ

1. https://dashboard.plaid.com/signup で登録し、Trial プラン（無料、10 件の Item）を選択します。
2. Team Settings → Products：Transactions、Liabilities、Investments を有効にします。
3. Team Settings → API：client_id と本番用の secret をコピーします。

2. インストール

git clone https://github.com/JosueM1109/personal-finance-mcp.git
cd personal-finance-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then fill in PLAID_CLIENT_ID and PLAID_SECRET
pytest -v              # sanity check

3. 各銀行をリンク

接続する銀行ごとに 1 回実行します：

uvicorn link_helper:app --port 8765

http://localhost:8765 を開き、Link a bank をクリックして Plaid Link を完了します。ターミナルに PLAID_TOKEN_CHASE=access-prod-xxx... のような行が表示されます。これを .env に貼り付け、銀行ごとに同じ手順を繰り返します。

4. 起動

python server.py   # serves on http://localhost:8000/mcp

5. Claude Code に追加

claude mcp add --transport http personal-finance http://localhost:8000/mcp

確認のため、「list my accounts」を試してください。

デプロイ

どこからでも利用できるようにデプロイする場合：

• Docker（付属）：docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcp
• 任意の Python ホスト（Fly.io、Railway、Raspberry Pi + Tailscale、VPS）：.env.example の環境変数を設定し、HTTPS 経由で /mcp を公開して、認証で保護します。
• Prefect Horizon（作者が利用している方法 — 継続的な費用は $0）：手順の詳細は docs/DEPLOYMENT.md を参照してください。

エンドポイントを保護してください。 トークンを含む公開 MCP エンドポイントからは、リンク済みのすべての口座情報が漏えいします。OAuth 2.1、Cloudflare Access を使用するか、プライベートネットワークのみにバインドしてください。

セキュリティ

• シングルテナント。 1人につき1つのデプロイです。共有しないでください。
• 読み取り専用。 どの金融機関でも、ツールが状態を変更することはありません。そのようなツールは追加しないでください。
• トークンは環境変数に保存し、ディスクには保存しません。.env は Git の追跡対象外です。
• Plaid のコンプライアンス対応はご自身の責任です。 ご自身のアカウントで Plaid を利用する顧客はご自身です。

デプロイする前に、以下を確認してください。

• .env がコミットされていないこと：git log --all -- .env の結果が空である
• 履歴に実際のトークンが含まれていないこと：git log -S'access-prod-' --all の結果にプレースホルダーのみが表示される
• MCP エンドポイントの前段に認証ゲートがあること（または localhost のみでアクセスできること）
• デプロイ環境で HORIZON=1（または同等の設定）が設定され、そこで link_helper.py がブロックされること
• 再認証が必要か確認するため、数週間ごとに get_institutions_status() を確認すること

トラブルシューティング

実際のデータがあるのに、ツールの結果が空です。 銀行をリンクしたときに、Plaid のプロダクトが有効になっていませんでした。Transactions、Liabilities、Investments を有効にして再リンクしてください。これが原因の場合、ツールは warnings に PRODUCTS_NOT_SUPPORTED を表示します。

get_institutions_status() に re_auth_required と表示されます。 銀行の Plaid セッションの有効期限が切れています。更新モードで link_helper.py を実行してください。既存のアクセストークンは変わりません。docs/DEPLOYMENT.md を参照してください。

Plaid Link で銀行が「unsupported」と表示されます（Amex でよくあります）。 通常、INSTITUTION_REGISTRATION_REQUIRED の問題です。OAuth 対応の銀行では、事前に Plaid ダッシュボードで金融機関ごとの登録が必要です。docs/TROUBLESHOOTING.md を参照してください。

その他の問題については、docs/TROUBLESHOOTING.md を参照してください。

アーキテクチャ

• server.py — FastMCP サーバー。読み取り専用のツールが9つあります。
• plaid_client.py — Plaid SDK のラッパー：SecretStr によるトークンの秘匿、Item ごとの5分間のヘルスキャッシュ、レスポンスの整形、構造化されたエラーマッピング。
• link_helper.py — Plaid Link 用のローカル専用 FastAPI アプリ。HORIZON=1 が設定されている場合は実行を拒否します。

（/transactions/sync ではなく /transactions/get を使う理由を含む）詳しい説明は、docs/ARCHITECTURE.md を参照してください。

コントリビューション

CONTRIBUTING.md を参照してください。対象範囲は意図的に限定されています：読み取り専用、シングルテナント、Plaid を利用。