pluggy-mcp-server

Un servidor MCP de solo lectura que expone tus datos financieros personales (Open Finance brasileño, vía Pluggy) a cualquier cliente MCP — Claude Code, Cursor, Cline, Zed.

Una alternativa autoalojada a los servicios de "banco sobre MCP" de pago: Meu Pluggy es gratuito sin fecha de caducidad para personas que acceden a sus propios datos a través de la API.

Sin movimiento de dinero. No hay PIX, ni transferencias, ni pagos. El PaymentsClient de Pluggy nunca se importa, y una prueba falla si alguien lo importa.

Herramientas

Los importes están normalizados para que negativo siempre signifique dinero que sale de la cuenta, tanto en cuentas bancarias como en tarjetas de crédito. Los datos brutos de Pluggy difieren entre ambos, lo que hace que el gasto con tarjeta cancele el gasto bancario si se suman ingenuamente. También están siempre en la moneda propia de la cuenta: Pluggy informa una compra en el extranjero en la moneda del comercio, por lo que se usa el valor convertido y el original se conserva en valor_orig para conciliación.

No todas las cuentas están en reales. list_accounts, list_investments y list_investment_transactions incluyen una columna currency, porque una correduría offshore informa saldos y posiciones en USD junto a las brasileñas. El patrimonio neto y los totales de la cartera solo tienen sentido por moneda, a menos que conviertas y lo indiques.

En una tarjeta de crédito, date es la fecha de publicación, no la de compra — una cuota de una compra de hace un año se publica este mes. data_compra lleva la fecha original cuando ambas difieren, y fatura indica en qué factura aterrizó la fila, de modo que list_transactions({ bill }) devuelve las partidas detrás del total de una factura.

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

Prompts

Análisis guardados, para que la misma pregunta se haga de la misma manera cada mes.

Configuración

1. Conecta tus bancos (una vez, ~15 min)

1. Crea una cuenta en meu.pluggy.ai y conecta tus bancos

2. Crea una cuenta en dashboard.pluggy.ai. Esto inicia una prueba de 15 días, que puedes ignorar: Pluggy afirma que aún puedes extraer tus datos después de que expire

3. Antes de crear la aplicación, ve a Customize y añade el conector MeuPluggy a tu lista de conectores. Si te lo saltas, no aparecerá más tarde

4. Crea una Development Application y copia su Client ID y Client Secret

5. Abre la aplicación Demo y vincula tu cuenta de Meu Pluggy mediante la autorización OAuth de MeuPluggy. Repite esto una vez por banco conectado — Pluggy emite un item por banco, no por cuenta

6. Copia el Item ID de cada conexión ("Copiar Item ID")

Los nombres de las conexiones se derivan de los nombres de cuenta que informa Pluggy, por lo que un banco nuevo no necesita configuración. Cuando un item no nombra ninguna institución en ningún sitio — algunos informan todas las cuentas como Conta Corrente — nómbralo tú mismo con PLUGGY_ITEM_LABELS=<item id>=Banco X, separado por comas si hay más de uno.

El conector 200 actúa como proxy sobre las conexiones que posee Meu Pluggy y las actualiza a diario. Como Meu Pluggy las posee, Pluggy se niega a sincronizarlas a través de la API — refresh_connection responde 400 MeuPluggy item cant be updated e indica dónde ir en su lugar. Forzar una actualización significa reconectar el banco en meu.pluggy.ai, y una ventana que falta en tu historial solo vuelve si el banco aún la expone a través de Open Finance.

2. Comprueba qué devuelve realmente el conector 200

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

npm run setup enmascara el client secret mientras lo escribes, genera el token bearer de MCP por ti y verifica las credenciales contra la API de Pluggy antes de escribir nada. Volver a ejecutarlo conserva tus valores actuales — pulsa Enter para omitir un prompt.

La sonda informa si las inversiones, las facturas de tarjetas de crédito y los préstamos están disponibles en tus conexiones, y valida el manejo de fechas y categorías. No imprime números de cuenta, identificaciones fiscales ni descripciones de transacciones.

3. Ejecuta

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

Comprueba que está vivo con curl localhost:8787/health.

Despliegue (VM + Tailscale)

El proceso escucha solo en loopback. La exposición la gestiona Tailscale, nunca enlazando a 0.0.0.0 — las VMs en la nube tienen IPs públicas, y un bind incorrecto combinado con una lista de seguridad abierta pone tu extracto bancario en internet.

La VM necesita Node 22.6+ y Tailscale ya activo (tailscale up). El archivo unit ejecuta /usr/bin/node, que es donde aterriza un paquete de distro o NodeSource; si instalaste Node mediante nvm, apunta ExecStart al binario real en su lugar.

1. Cuenta de servicio y código

El servicio nunca escribe en disco — la caché está en memoria, y el unit establece ProtectSystem=strict con un ReadWritePaths vacío. Así que el código es propiedad de root y el usuario del servicio solo lo lee: un proceso comprometido no puede reescribir su propio código fuente.

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

Ejecuta la configuración en la VM en lugar de copiar un .env por scp. Verifica las credenciales contra la API de Pluggy antes de escribir nada, lo que también demuestra que la VM tiene conectividad saliente — algo que vale la pena saber antes de que systemd esté en juego.

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

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

Confirma que llegó a Pluggy, no solo que el puerto responde:

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

El journal debería terminar en transaction cache warmed. Si en cambio dice cache warm failed con un error de resolución de nombres, la causa es RestrictAddressFamilies en el unit: donde glibc resuelve a través de systemd-resolved, getaddrinfo necesita un socket unix. Añade AF_UNIX a esa línea y reinicia.

4. Publica en la tailnet

Comprueba qué publica ya el nodo antes de reclamar un puerto — serve reemplaza un handler en el mismo puerto y ruta sin aviso, y tomar / en 443 de un servicio que ya está ahí es una caída silenciosa:

sudo tailscale serve status   # empty output means 443 is free

Si 443 está libre, úsalo. Si algo ya lo ocupa, monta en otro puerto HTTPS en lugar de compartir la ruta:

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

Esto requiere HTTPS habilitado para la tailnet (consola de administración > DNS). El certificado es real y se emite automáticamente, por lo que el token bearer nunca viaja en claro. La configuración de serve sobrevive a los reinicios, así que este es un comando único.

Conecta un cliente

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

La URL tiene que ir antes de --header. Ese flag es variádico, así que cualquier cosa después se analiza como otro header y la URL nunca llega al argumento posicional.

Localmente, contra 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-)"

Esto no funciona en Claude web ni en la aplicación móvil: los conectores personalizados de claude.ai se marcan desde la infraestructura de Anthropic, que no puede alcanzar una tailnet privada. Los clientes que se conectan desde la máquina en la que se ejecutan funcionan con normalidad.

Actualización

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

Rotar el token bearer es el mismo reinicio: edita /etc/pluggy-mcp/env, reinicia el servicio y actualiza el header en cada cliente.

O deja que la máquina lo haga: un timer de systemd puede rastrear origin/main, reconstruir cuando se mueve y revertir si el nuevo commit no vuelve sano. Dos archivos para copiar — ver deploy/README.md.

Diseño

Cada decisión y su razonamiento está en DESIGN.md.

Licencia

MIT