pluggy-mcp-server

Только для чтения MCP-сервер, который предоставляет ваши личные финансовые данные (бразильский Open Finance, через Pluggy) любому MCP-клиенту — Claude Code, Cursor, Cline, Zed.

Самостоятельно размещаемая альтернатива платным сервисам «банк через MCP»: Meu Pluggy бесплатен и не имеет срока действия для частных лиц, получающих доступ к своим данным через API.

Никаких денежных переводов. Нет PIX, нет переводов, нет платежей. PaymentsClient от Pluggy никогда не импортируется, и тест завершается ошибкой, если кто-то его импортирует.

Инструменты

Суммы нормализованы так, что отрицательное значение всегда означает уход денег со счёта, как на банковских счетах, так и на кредитных картах. Необработанные данные 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 и свяжите свой аккаунт Meu Pluggy через авторизацию OAuth MeuPluggy. Повторите это один раз для каждого подключённого банка — Pluggy выдаёт один элемент на банк, а не на счёт

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 bearer-токен и проверяет учётные данные через API Pluggy перед записью чего-либо. Повторный запуск сохраняет текущие значения — нажмите Enter, чтобы пропустить запрос.

Проба сообщает, доступны ли инвестиции, счета по кредитным картам и кредиты на ваших подключениях, а также проверяет обработку дат и категорий. Она не выводит номера счетов, налоговые идентификаторы или описания транзакций.

3. Запуск

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

Проверьте, что он работает, с помощью curl localhost:8787/health.

Развёртывание (VM + Tailscale)

Процесс прослушивает только loopback. Доступ обеспечивается через Tailscale, а не привязкой к 0.0.0.0 — облачные VM имеют публичные IP-адреса, и неправильная привязка в сочетании с открытым списком безопасности выставит вашу банковскую выписку в интернет.

VM нужен Node 22.6+ и уже запущенный Tailscale (tailscale up). Unit-файл запускает /usr/bin/node — именно там оказывается пакет дистрибутива или NodeSource; если вы установили Node через nvm, укажите 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. Учётные данные

Запустите настройку на VM, а не копируйте .env через scp. Она проверяет учётные данные через API Pluggy перед записью чего-либо, что также доказывает, что 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 в unit: там, где glibc разрешает через systemd-resolved, getaddrinfo нужен unix-сокет. Добавьте 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

Это требует включённого HTTPS для tailnet (админ-консоль > DNS). Сертификат настоящий и выдаётся автоматически, поэтому bearer-токен никогда не передаётся открытым текстом. Конфигурация 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 или мобильном приложении: пользовательские коннекторы 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-токена — это тот же перезапуск: отредактируйте /etc/pluggy-mcp/env, перезапустите сервис и обновите заголовок на каждом клиенте.

Или позвольте машине сделать это: системный таймер может отслеживать origin/main, пересобирать при его изменении и откатываться, если новый коммит не вернулся здоровым. Два файла для копирования — см. deploy/README.md.

Дизайн

Каждое решение и его обоснование — в DESIGN.md.

Лицензия

MIT