pluggy-mcp-server

読み取り専用のMCPサーバーで、あなたの個人財務データ（ブラジルのOpen Finance、Pluggy経由）を任意のMCPクライアント（Claude Code、Cursor、Cline、Zed）に公開します。

有料の「銀行×MCP」サービスのセルフホスト代替です。Meu Pluggyは、API経由で自分のデータにアクセスする個人にとって無料で有効期限なしです。

送金機能はありません。 PIX、振込、支払いは一切ありません。PluggyのPaymentsClientはインポートされず、誰かがインポートするとテストが失敗します。

ツール

金額は正規化され、負の値は常に口座からの支出を意味します（銀行口座とクレジットカードの両方で）。Pluggyの生データはこの2つで食い違うため、単純に合算するとカード支出が銀行支出を相殺してしまいます。また、常に口座の通貨で表示されます。Pluggyは海外購入を加盟店通貨で報告するため、換算後の値を使用し、元の値はvalor_origに保持して照合できるようにしています。

すべての口座がレアルであるとは限りません。list_accounts、list_investments、list_investment_transactionsにはすべてcurrency列があり、オフショア証券会社がブラジルの口座と並んでUSD残高とポジションを報告するためです。純資産とポートフォリオ合計は、換算して明示しない限り、通貨ごとにのみ意味を持ちます。

クレジットカードでは、dateは起票日であり、購入日ではありません。1年前の購入の分割払いが今月起票されることもあります。data_compraには両者が異なる場合の元の日付が入り、faturaはその行がどの請求書に載ったかを示します。したがって、list_transactions({ bill })は請求書合計の内訳を返します。

Related MCP server: @gu-does-packages/pluggy-mcp

プロンプト

保存された分析で、毎月同じ質問を同じ方法で行えます。

セットアップ

1. 銀行を接続する（一度だけ、約15分）

1. meu.pluggy.aiでアカウントを作成し、銀行を接続します

2. dashboard.pluggy.aiでアカウントを作成します。これで15日間のトライアルが始まりますが、無視して構いません。Pluggyは有効期限が切れてもデータを取得できると明言しています

3. アプリケーションを作成する前に、Customizeに移動し、MeuPluggyコネクタをコネクタリストに追加します。これをスキップすると、後で表示されません

4. Development Applicationを作成し、Client IDとClient Secretをコピーします

5. Demoアプリケーションを開き、MeuPluggyのOAuth認証を通じてMeu Pluggyアカウントをリンクします。接続した銀行ごとにこれを繰り返します — Pluggyは口座ごとではなく銀行ごとに1つのアイテムを発行します

6. 各接続のItem IDをコピーします（「Copiar Item ID」）

接続名はPluggyが報告する口座名から派生するため、新しい銀行は設定不要です。アイテムがどこにも機関名を付けない場合（一部はすべての口座をConta Correnteと報告します）、PLUGGY_ITEM_LABELS=<item id>=Banco Xで自分で名前を付けます。複数の場合はカンマ区切りです。

コネクタ200はMeu Pluggyが所有する接続のプロキシとして機能し、毎日更新します。Meu Pluggyが所有しているため、PluggyはAPI経由での同期を拒否します — refresh_connectionは400 MeuPluggy item cant be updatedと応答し、代わりにどこで行うべきかを示します。強制的に更新するにはmeu.pluggy.aiで銀行を再接続する必要があり、履歴に欠落した期間は、銀行がOpen Financeでまだ公開している場合にのみ戻ってきます。

2. コネクタ200が実際に何を返すか確認する

npm install
npm run setup   # prompts for the credentials, writes .env with mode 0600
npm run probe

npm run setupは、入力中にクライアントシークレットをマスクし、MCPベアラートークンを生成し、何かを書き込む前にPluggy APIに対して資格情報を検証します。再実行すると現在の値が保持されます — プロンプトをスキップするにはEnterを押します。

プローブは、投資、クレジットカード請求書、ローンが接続で利用可能かどうかを報告し、日付とカテゴリの処理を検証します。口座番号、税ID、取引の説明は印刷しません。

3. 実行

npm run dev            # development, reads .env directly
npm run build && npm start   # production

curl localhost:8787/healthで稼働を確認します。

デプロイ（VM + Tailscale）

プロセスはループバックのみで待ち受けます。公開はTailscaleが処理し、0.0.0.0へのバインドは決して行いません — クラウドVMにはパブリックIPがあり、誤ったバインドとオープンなセキュリティリストの組み合わせは、銀行明細をインターネットにさらすことになります。

VMにはNode 22.6+とTailscaleが起動済み（tailscale up）である必要があります。ユニットファイルは/usr/bin/nodeを実行します。これはディストリビューションまたはNodeSourceパッケージが配置される場所です。nvmでNodeをインストールした場合は、ExecStartを実際のバイナリに指定してください。

1. サービスアカウントとコード

サービスはディスクに書き込みません — キャッシュはメモリ内にあり、ユニットは空のReadWritePathsでProtectSystem=strictを設定します。したがって、コードはrootが所有し、サービスユーザーは読み取りのみ可能です。侵害されたプロセスは自身のソースを書き換えられません。

sudo useradd --system --no-create-home --shell /usr/sbin/nologin pluggy-mcp

sudo git clone https://github.com/brunopedrazza/pluggy-mcp-server /opt/pluggy-mcp
cd /opt/pluggy-mcp
sudo npm ci                  # dev dependencies included: tsc is needed to build
sudo npm run build
sudo npm prune --omit=dev    # and dropped again; free-tier VMs are small

2. 資格情報

scpで.envをコピーするのではなく、VM上でセットアップを実行します。何かを書き込む前にPluggy APIに対して資格情報を検証するため、VMにアウトバウンド接続があることも証明されます — systemdを導入する前に知っておく価値があります。

sudo npm run setup

sudo install -d -m 700 /etc/pluggy-mcp
sudo install -m 600 .env /etc/pluggy-mcp/env
sudo rm /opt/pluggy-mcp/.env   # one copy of the secret, not two

3. サービス

sudo cp deploy/pluggy-mcp.service /etc/systemd/system/
sudo systemctl enable --now pluggy-mcp

ポートが応答するだけでなく、Pluggyに到達したことを確認します:

curl localhost:8787/health
journalctl -u pluggy-mcp -n 20

ジャーナルはtransaction cache warmedで終わるはずです。代わりに名前解決エラーでcache warm failedと表示される場合、原因はユニットのRestrictAddressFamiliesです。glibcがsystemd-resolved経由で解決する場合、getaddrinfoはunixソケットを必要とします。その行にAF_UNIXを追加して再起動してください。

4. テールネットに公開する

ポートを主張する前に、ノードがすでに公開しているものを確認してください — serveは同じポートとパス上のハンドラーを警告なしに置き換え、すでに存在するサービスから443の/を奪うと、静かな障害が発生します:

sudo tailscale serve status   # empty output means 443 is free

443が空いていれば使用します。すでに何かが保持している場合は、パスを共有する代わりに別のHTTPSポートにマウントします:

sudo tailscale serve --bg --https=8443 127.0.0.1:8787
sudo tailscale serve status   # prints the https://…ts.net URL used below

これにはテールネットでHTTPSが有効である必要があります（管理コンソール > DNS）。証明書は本物で自動的に発行されるため、ベアラートークンが平文で送信されることはありません。serve設定は再起動後も存続するため、これは一度だけのコマンドです。

クライアントを接続する

claude mcp add --transport http pluggy https://YOUR-VM.YOUR-TAILNET.ts.net/mcp \
  --header "Authorization: Bearer $MCP_BEARER_TOKEN"

URLは--headerの前に置く必要があります。そのフラグは可変長なので、その後に続くものはすべて別のヘッダーとして解析され、URLが位置引数に到達しません。

ローカルでnpm run devに対して:

claude mcp add --transport http pluggy http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $(grep '^MCP_BEARER_TOKEN=' .env | cut -d= -f2-)"

これはClaude Webやモバイルアプリでは機能しません。claude.aiのカスタムコネクタはAnthropicのインフラストラクチャからダイヤルされるため、プライベートテールネットに到達できません。実行中のマシンから接続するクライアントは正常に動作します。

更新

cd /opt/pluggy-mcp
sudo git pull && sudo npm ci && sudo npm run build && sudo npm prune --omit=dev
sudo systemctl restart pluggy-mcp

ベアラートークンのローテーションも同じ再起動です。/etc/pluggy-mcp/envを編集し、サービスを再起動し、すべてのクライアントのヘッダーを更新します。

または、ボックスに任せることもできます。systemdタイマーでorigin/mainを追跡し、移動したら再ビルドし、新しいコミットが正常に戻らない場合はロールバックします。コピーするファイルは2つです — deploy/README.mdを参照してください。

設計

すべての決定とその理由はDESIGN.mdにあります。

ライセンス

MIT