pluggy-mcp-br

Ponte somente leitura entre o Grok Bot e os seus dados bancários brasileiros. Os dados vêm da Pluggy, no plano pessoal gratuito Meu Pluggy, que por sua vez lê instituições do Open Finance.

Isto não é “o Open Finance brasileiro”. É um conector MCP que o seu bot consulta. Quem publica este repositório não recebe chave, senha nem extrato: cada pessoa sobe o próprio servidor e usa as próprias credenciais.

O que dá para perguntar

Não há Pix, pagamento, transferência nem qualquer escrita. A API da Pluggy, daqui, só recebe POST /auth e GET.

Related MCP server: C6 Bank MCP

Privacidade

• Credenciais da Pluggy ficam só em variáveis de ambiente do seu servidor.

• Transações não são gravadas em disco nem em banco. O cache é memória do processo, com TTL padrão de 60 segundos (teto de 300). Na Vercel isso dura só enquanto a instância está quente, de propósito: extrato não vai para um cache compartilhado.

• CPF válido vira ***.***.***-XX. Número de conta e cartão ficam só com os quatro últimos dígitos.

• A descrição da transação é dado não confiável. Ela volta no campo texto_nao_confiavel, com um aviso de que não é instrução. Um texto de extrato pedindo Pix ou “ignore as instruções” não deve ser obedecido.

• O OAuth deste servidor tem um único usuário: o dono, que prova a senha OWNER_PASSWORD. Não há cadastro de outras pessoas.

• O resultado da ferramenta segue para o Grok Bot e, portanto, para o provedor do modelo. Este repositório não fica no meio, mas o bot que você conectar vê o que a ferramenta devolver.

Limites que não são deste código

• O Meu Pluggy atualiza os bancos cerca de uma vez a cada 24 horas. Este conector não força atualização.

• A autorização do conector MeuPluggy dura 1 ano. A data está em consentExpiresAt. Quando vence, as leituras voltam vazias até você autorizar de novo no dashboard. O consentimento de cada banco, dentro do Meu Pluggy, é outro prazo.

• Só entram instituições que o Open Finance e o Meu Pluggy oferecem. Uso pessoal, até 5 conexões, sem uso comercial. O guia oficial é Personal use: Meu Pluggy.

• GET /v2/items não existe nesse plano. Copie cada itemId na tela Demo.

• A categoria da Pluggy pode vir vazia no plano gratuito (o categorizador é recurso Pro). Aí o gasto cai em Sem categoria.

• A chave de API da Pluggy dura 2 horas. O servidor renova com POST /auth e não pede para você colar essa chave.

Limites conhecidos

• O reuso do código OAuth (cada código vale uma vez) e o limite de tentativas de senha ficam na memória da instância. Na Vercel, com várias instâncias, isso é parcial: outra instância pode não ter visto o código nem as falhas. Para cortar o acesso, troque OAUTH_SIGNING_SECRET.

• npm audit avisa do postcss trazido pelo Next.js. A correção exige next@16. Este projeto permanece no Next 15. Não use npm audit fix --force.

Modo demo

O padrão é DATA_MODE=demo. Não chama a Pluggy e não precisa de chave. Os números são fictícios, inclusive um Nubank inventado, para você ver as seis ferramentas sem expor banco de verdade.

npm install
npm test
npm run demo:mcp

demo:mcp sobe o servidor em loopback, faz o OAuth do dono e imprime uma chamada MCP real de cada ferramenta. Se OWNER_PASSWORD já estiver no ambiente, o script usa essa senha. Só quando ela não existe é que o processo recebe senha-demo-local-123, sem gravar arquivo.

Para ler dados de verdade, ou o conector Sandbox da Pluggy, use DATA_MODE=live com as variáveis abaixo. A interface das ferramentas é a mesma. O Sandbox também exige Client ID, Client Secret e um itemId: só o modo demo funciona sem conta Pluggy.

Passo a passo

1. Meu Pluggy e o banco

1. Crie a conta em meu.pluggy.ai.

2. Conecte cada banco lá. É nessa etapa que o banco pede CPF e aprovação no aplicativo. Cada banco é uma autorização separada.

3. Para o Nubank, escolha Nubank na lista do Meu Pluggy e conclua o consentimento do Open Finance no app do Nubank. O nome exato do botão muda com o app; o que importa é terminar a autorização do Open Finance, não digitar a senha do banco neste repositório.

2. Conector MeuPluggy no dashboard

1. Entre no dashboard da Pluggy com a mesma conta.

2. Se a aplicação usa seleção manual de conectores, ligue MeuPluggy em Customization → Connectors (grupo Personal, aba Direct Connectors).

3. Abra Applications → a sua aplicação → Demo → Connect Account.

4. No widget, escolha MeuPluggy. Não escolha o banco de novo e não escolha Sandbox, a menos que você queira dados de teste da Pluggy.

5. Entre com a conta do Meu Pluggy.

Se o widget pedir CPF e aprovação do banco outra vez, você escolheu o conector do banco em vez de MeuPluggy. Volte e escolha MeuPluggy.

Cada banco ligado no Meu Pluggy vira um item dessa aplicação. Copie o itemId em Connected Items. O Client ID aparece na linha da aplicação. O Client Secret só é mostrado uma vez: se você não guardou, gere outro na página da aplicação.

3. Variáveis

Copie .env.example. No modo live:

Não commite .env. Trocar OAUTH_SIGNING_SECRET invalida as sessões. Os redirects abaixo já são aceitos e não entram na variável extra:

• cursor://anysphere.cursor-mcp/oauth/callback

• https://www.cursor.com/agents/mcp/oauth/callback

• http://localhost:8787/callback

http://localhost:8787/callback é o callback do Grok Bot / Cursor, não a porta deste servidor. Localmente o servidor usa PORT (padrão 3333), só em 127.0.0.1.

4. Deploy na Vercel

O projeto já tem vercel.json e rotas Next.js. O deploy fica com você. Este repositório não dispara produção sozinho.

1. Importe o repositório em vercel.com/new. O plano Hobby serve.

2. Framework: Next.js. Não precisa mudar o comando de build.

3. Em Settings → Environment Variables, coloque as variáveis do modo que você quer. Para um primeiro deploy sem banco, DATA_MODE=demo mais OWNER_PASSWORD, OAUTH_SIGNING_SECRET e PUBLIC_URL já bastam.

4. PUBLIC_URL tem de ser a origem que você vai entregar ao bot, com https, sem /mcp. Se usar domínio próprio, não deixe o valor em *.vercel.app.

5. Faça o deploy quando quiser. Anote a URL https://SEU-DOMINIO/mcp.

Confira, sem token, no navegador:

• https://SEU-DOMINIO/.well-known/oauth-protected-resource/mcp

• https://SEU-DOMINIO/.well-known/oauth-authorization-server

Os dois precisam abrir em JSON. POST /mcp sem token deve responder 401 com WWW-Authenticate apontando para o primeiro.

5. Grok Bot

No chat do bot, peça para adicionar o conector, por exemplo:

Adicione este servidor MCP: https://SEU-DOMINIO/mcp

O bot só autentica conector custom por OAuth. Não há token fixo para colar. Ele registra o cliente, abre o login e você digita OWNER_PASSWORD. Na tela seguinte as ferramentas passam a existir.

O servidor é stateless: código, access token e refresh token são JWT assinados com OAUTH_SIGNING_SECRET. Não há banco de sessões. O refresh não dá para revogar um a um; para cortar o acesso, troque o segredo ou a senha e peça para conectar de novo.

6. Se o OAuth do bot falhar

Há relatos no fórum do Cursor (conectores custom do Grok Bot e redirect_uri não permitido). O que este servidor faz a respeito:

• Aceita, num único registro dinâmico, os três redirects que o cliente envia, inclusive cursor://. Provedores que recusam esse esquema quebram o registro inteiro. Aqui o esquema é permitido de propósito.

• Cliente público, PKCE S256, sem client secret. Se o cliente mandar Authorization básico ou client_secret no token, o valor é ignorado.

• O teste automático deste repositório registra os três URIs, erra a senha, acerta a senha e chama as ferramentas. Isso não é o Grok Bot de verdade: falta uma URL pública e a sua conta do bot.

Fallback, se o bot falhar:

1. fetch failed antes da tela de login: a URL não está pública em HTTPS. Preview com proteção, localhost e VPN não servem para o bot, que roda na nuvem. O mesmo URL pode funcionar no Cursor IDE, porque lá o OAuth sai da sua máquina.

2. Erro de redirect_uri: copie o URI exato da mensagem para OAUTH_EXTRA_REDIRECT_URIS e faça um novo deploy. Não apague os três já embutidos.

3. Não existe, no Grok Bot, um lugar seguro para token fixo ou header secreto. Não contorne com segredo no chat.

4. Enquanto o bot não conectar, dá para usar a mesma URL no mcp.json do Cursor IDE. Isso não liga o bot.

Desenvolvimento

npm install
npm run dev      # http://127.0.0.1:3333/mcp
npm test
npm run typecheck
npm run build    # confere o bundle da Vercel, não publica

npm run dev sem OWNER_PASSWORD sobe o modo demo, mas o login responde que a senha não foi configurada. npm run demo:mcp usa a OWNER_PASSWORD que já estiver no ambiente; se não houver, define senha-demo-local-123 só naquele processo e não grava arquivo.

As ferramentas no modo demo e o mascaramento estão em test/. test/mcp-http.test.ts sobe o HTTP de verdade e fala o protocolo MCP.

Licença

MIT. Pluggy, Nubank, Open Finance e Cursor são marcas de seus donos. Este projeto não é afiliado a eles.