pluggy-mcp-server

A read-only MCP server that exposes your personal financial data (Brazilian Open Finance, via Pluggy) to any MCP client — Claude Code, Cursor, Cline, Zed.

A self-hosted alternative to paid "bank over MCP" services: Meu Pluggy is free with no expiration date for individuals accessing their own data over the API.

No money movement. There is no PIX, no transfer, no payment. Pluggy's PaymentsClient is never imported, and a test fails if anyone imports it.

Tools

Tool	What it does
list_connections	Connections, status, and data freshness per product
list_accounts	Checking, savings and credit card accounts, with balances
list_transactions	Statement as TSV: posting date, purchase date, installment, and the bill each row landed on
search_transactions	Search by text, amount range and category, across accounts
list_credit_card_bills	Bills: due date, closing date, total, payments, finance charges
list_investments	Current portfolio positions, each with its own currency
list_investment_transactions	Contributions and withdrawals, to compute returns
list_loans	Loans and financing: outstanding balance, rates, installments
refresh_connection	Triggers a Pluggy sync (non-blocking)

Amounts are normalised so negative always means money leaving the account, on bank accounts and credit cards alike. Pluggy's raw data disagrees between the two, which makes card spending cancel bank spending if summed naively. They are also always in the account's own currency: Pluggy reports a foreign purchase in the merchant's currency, so the converted value is used and the original is kept in valor_orig for reconciliation.

Not every account is in reais. list_accounts, list_investments and list_investment_transactions all carry a currency column, because an offshore brokerage reports USD balances and positions beside the Brazilian ones. Net worth and portfolio totals are only meaningful per currency unless you convert and say so.

On a credit card, date is the posting date, not the purchase date — an instalment of a year-old purchase posts this month. data_compra carries the original date where the two differ, and fatura says which bill the row landed on, so list_transactions({ bill }) returns the line items behind a bill total.

Prompts

Saved analyses, so the same question is asked the same way each month.

Prompt	What it does
analise_mensal	A month end to end: in, out, categories, and the change against the month before
fatura_cartao	One bill: reconciled against the bank's total, new purchases split from instalments of old ones
revisao_assinaturas	Recurring charges, including the forgotten ones and the ones that went up
saude_financeira	Net worth, debt, credit usage and savings rate

Setup

1. Connect your banks (once, ~15 min)

1. Create an account at meu.pluggy.ai and connect your banks
2. Create an account at dashboard.pluggy.ai. This starts a 15-day trial, which you can ignore: Pluggy states you can still pull your data after it expires
3. Before creating the application, go to Customize and add the MeuPluggy connector to your connector list. Skip this and it will not show up later
4. Create a Development Application and copy its Client ID and Client Secret
5. Open the Demo application and link your Meu Pluggy account through the MeuPluggy OAuth authorization. Repeat this once per connected bank — Pluggy issues one item per bank, not per account
6. Copy the Item ID of each connection ("Copiar Item ID")

Connection names are derived from the account names Pluggy reports, so a new bank needs no configuration. When an item names no institution anywhere — some report every account as Conta Corrente — name it yourself with PLUGGY_ITEM_LABELS=<item id>=Banco X, comma-separated for more than one.

Connector 200 acts as a proxy over the connections Meu Pluggy owns, and refreshes them daily. Because Meu Pluggy owns them, Pluggy refuses to sync them through the API — refresh_connection answers 400 MeuPluggy item cant be updated and says where to go instead. Forcing an update means reconnecting the bank at meu.pluggy.ai, and a window missing from your history only comes back if the bank still exposes it over Open Finance.

2. Check what Connector 200 actually returns

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

npm run setup masks the client secret while you type it, generates the MCP bearer token for you, and verifies the credentials against the Pluggy API before writing anything. Re-running it keeps your current values — press Enter to skip a prompt.

The probe reports whether investments, credit card bills and loans are available on your connections, and validates date and category handling. It does not print account numbers, tax IDs, or transaction descriptions.

3. Run

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

Check it is alive with curl localhost:8787/health.

Deployment (VM + Tailscale)

The process listens on loopback only. Exposure is handled by Tailscale, never by binding to 0.0.0.0 — cloud VMs have public IPs, and a wrong bind combined with an open security list puts your bank statement on the internet.

The VM needs Node 22.6+ and Tailscale already up (tailscale up). The unit file runs /usr/bin/node, which is where a distro or NodeSource package lands; if you installed Node through nvm, point ExecStart at the real binary instead.

1. Service account and code

The service never writes to disk — the cache is in memory, and the unit sets ProtectSystem=strict with an empty ReadWritePaths. So the code is owned by root and the service user only reads it: a compromised process cannot rewrite its own source.

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. Credentials

Run the setup on the VM rather than copying a .env over scp. It verifies the credentials against the Pluggy API before writing anything, which also proves the VM has outbound connectivity — worth knowing before systemd is in the picture.

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. Service

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

Confirm it reached Pluggy, not just that the port answers:

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

The journal should end in transaction cache warmed. If instead it says cache warm failed with a name resolution error, the cause is RestrictAddressFamilies in the unit: where glibc resolves through systemd-resolved, getaddrinfo needs a unix socket. Add AF_UNIX to that line and restart.

4. Publish on the tailnet

Check what the node already publishes before claiming a port — serve replaces a handler on the same port and path without warning, and taking / on 443 from a service already there is a silent outage:

sudo tailscale serve status   # empty output means 443 is free

If 443 is free, use it. If something already holds it, mount on another HTTPS port instead of sharing the path:

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

This requires HTTPS enabled for the tailnet (admin console > DNS). The certificate is real and issued automatically, so the bearer token never travels in the clear. Serve config survives reboots, so this is a one-time command.

Connect a client

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

The URL has to come before --header. That flag is variadic, so anything after it is parsed as another header and the URL never reaches the positional argument.

Locally, against 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-)"

This does not work in Claude web or the mobile app: claude.ai custom connectors are dialed by Anthropic's infrastructure, which cannot reach a private tailnet. Clients that connect from the machine they run on work normally.

Updating

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

Rotating the bearer token is the same restart: edit /etc/pluggy-mcp/env, restart the service, and update the header on every client.

Or let the box do it: a systemd timer can track origin/main, rebuild when it moves, and roll back if the new commit doesn't come back healthy. Two files to copy — see deploy/README.md.

Design

Every decision and its reasoning is in DESIGN.md.

License

MIT