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つの銀行でエラーが発生してもクエリ全体が停止することはありません。

クイックスタート

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

1. Plaidのセットアップ

1. https://dashboard.plaid.com/signup に登録し、Trialプラン（無料、10アイテムまで）を選択します。

2. Team Settings → Products で、Transactions、Liabilities、Investments を有効にします。

3. Team Settings → API で、client_id と本番環境の secret をコピーします。

2. インストール

git clone https://github.com/<you>/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 はgitignoredされています。

• 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で銀行が「サポート対象外」と表示される（Amexでよくある）。 通常は INSTITUTION_REGISTRATION_REQUIRED の問題です。OAuth対応の銀行は、まずPlaidダッシュボードで機関ごとの登録が必要です。docs/TROUBLESHOOTING.md を参照してください。

その他の問題: docs/TROUBLESHOOTING.md

アーキテクチャ

• server.py — FastMCPサーバー、9つの読み取り専用ツール。

• plaid_client.py — Plaid SDKラッパー: SecretStr トークンのマスキング、アイテムごとの5分間のヘルスキャッシュ、レスポンスの整形、構造化されたエラーマッピング。

• link_helper.py — Plaid Link用のローカル専用FastAPIアプリ。HORIZON=1 が設定されている場合は実行を拒否します。

詳細（なぜ /transactions/sync ではなく /transactions/get を使用しているかなど）: docs/ARCHITECTURE.md

コントリビューション

CONTRIBUTING.md を参照してください。スコープは意図的に狭く設定されています（読み取り専用、シングルテナント、Plaidベース）。