pluggy-mcp-server

一个只读 MCP 服务器，通过 Pluggy 将你的个人财务数据（巴西 Open Finance）暴露给任何 MCP 客户端——Claude Code、Cursor、Cline、Zed。

这是付费的“通过 MCP 访问银行”服务的自托管替代方案：Meu Pluggy 对通过 API 访问自己数据的个人用户免费且无过期时间。

不涉及资金转移。 没有 PIX，没有转账，没有支付。Pluggy 的 PaymentsClient 永远不会被导入，如果有任何人导入它，一个测试就会失败。

工具

所有金额都经过归一化，因此负数始终表示资金离开账户，无论是银行账户还是信用卡。Pluggy 的原始数据在两者之间不一致，如果直接求和，信用卡支出会抵消银行支出。金额也始终使用账户自身的货币：Pluggy 会以商户货币报告境外消费，因此使用换算后的数值，同时将原始值保留在 valor_orig 中以便对账。

并非所有账户都以雷亚尔计价。list_accounts、list_investments 和 list_investment_transactions 都带有 currency 列，因为离岸券商会在巴西账户之外报告美元余额和持仓。除非你进行换算并明确说明，否则净资产和投资组合总计仅在按货币分别计算时才有意义。

在信用卡上，date 是入账日期，而不是购买日期——一年前购买的一笔分期可能在本月入账。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 每家银行签发一个 item，而不是每个账户一个

6. 复制每个连接的 Item ID（“Copiar Item ID”）

连接名称来自 Pluggy 报告的账户名称，因此新银行无需配置。如果某个 item 在任何地方都没有机构名称——有些银行会把所有账户都报告为 Conta Corrente——你可以用 PLUGGY_ITEM_LABELS=<item id>=Banco X 自行命名，多个时用逗号分隔。

Connector 200 充当 Meu Pluggy 所拥有连接的代理，并每天刷新它们。由于这些连接归 Meu Pluggy 所有，Pluggy 拒绝通过 API 同步它们——refresh_connection 会返回 400 MeuPluggy item cant be updated，并告诉你应该去哪里操作。强制更新意味着需要在 meu.pluggy.ai 重新连接银行，而历史记录中缺失的时间窗口只有在银行仍然通过 Open Finance 提供该数据时才会恢复。

2. 检查 Connector 200 实际返回什么

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

npm run setup 会在你输入时掩蔽 client secret，为你生成 MCP bearer token，并在写入任何内容之前向 Pluggy API 验证凭据。重新运行会保留你当前的值——按 Enter 跳过某项提示。

该探测会报告你的连接上是否提供投资、信用卡账单和贷款，并验证日期和类别处理。它不会打印账号、税号或交易描述。

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 来实现——云虚拟机拥有公网 IP，错误的绑定加上开放的安全列表会把你的银行对账单暴露在互联网上。

虚拟机需要 Node 22.6+ 并且 Tailscale 已经启动（tailscale up）。unit 文件运行 /usr/bin/node，这是发行版或 NodeSource 包安装的位置；如果你通过 nvm 安装 Node，请将 ExecStart 指向实际的二进制文件。

1. 服务账户和代码

该服务从不写入磁盘——缓存位于内存中，unit 设置了 ProtectSystem=strict 和空的 ReadWritePaths。因此代码归 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. 凭据

在虚拟机上运行 setup，而不是通过 scp 复制 .env。它会在写入任何内容之前向 Pluggy API 验证凭据，这同时也证明虚拟机具有出站连接能力——在 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 并伴随名称解析错误，原因在于 unit 中的 RestrictAddressFamilies：在 glibc 通过 systemd-resolved 解析的环境中，getaddrinfo 需要 unix socket。将 AF_UNIX 添加到该行并重启。

4. 在 tailnet 上发布

在占用端口之前，先检查节点已经发布了什么——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

这需要为 tailnet 启用 HTTPS（管理员控制台 > DNS）。证书是真实的并且自动签发，因此 bearer token 永远不会明文传输。serve 配置在重启后仍然有效，所以这是一次性命令。

连接客户端

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

URL 必须放在 --header 之前。该标志是可变参数的，所以它后面的任何内容都会被解析为另一个 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 网页版或移动应用中无效：claude.ai 的自定义连接器由 Anthropic 的基础设施拨号连接，而该基础设施无法访问私有 tailnet。从自身运行的机器发起连接的客户端可以正常工作。

更新

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

轮换 bearer token 也是同样的重启流程：编辑 /etc/pluggy-mcp/env，重启服务，并在每个客户端上更新 header。

或者让机器自己完成：systemd 定时器可以跟踪 origin/main，在它更新时重新构建，如果新提交不能恢复正常运行，则回滚。需要复制两个文件——参见 deploy/README.md。

设计

每个决策及其理由都在 DESIGN.md 中。

许可证

MIT