PushinPay MCP Server
Official# @pushinpaybr/mcp-server
Servidor [MCP](https://modelcontextprotocol.io) oficial da **PushinPay**. Conecta agentes de IA (Claude Desktop, Claude Code, Cursor) à API PushinPay para operações PIX — sem escrever código de integração.
> **Status:** v1 (em construção). Escopo somente-leitura + criação de cobrança. **Não** expõe saque, reembolso ou alteração de conta, por segurança.
## Tools disponíveis
| Tool | Descrição |
|------|-----------|
| `consultar_saldo` | Saldo disponível e valor bloqueado da conta |
| `consultar_transacao` | Status de uma transação PIX pelo ID (trava de 1 consulta/min embutida) |
| `criar_cobranca_pix` | Cria cobrança PIX (copia-e-cola + QR Code), com split opcional |
> Escopo v1: por segurança, **não** há saque, reembolso nem alteração de conta.
## Uso rápido
Não precisa clonar nada — roda direto via `npx`:
```bash
npx -y @pushinpaybr/mcp-server
```
O servidor lê a configuração de variáveis de ambiente:
| Variável | Obrigatória | Padrão | Descrição |
|----------|-------------|--------|-----------|
| `PUSHINPAY_TOKEN` | sim | — | Token da sua conta (gere no painel) |
| `PUSHINPAY_ENV` | não | `sandbox` | `sandbox` ou `production` |
## Configuração no cliente de IA
### Claude Desktop / Claude Code
Adicione ao seu arquivo de config MCP:
```json
{
"mcpServers": {
"pushinpay": {
"command": "npx",
"args": ["-y", "@pushinpaybr/mcp-server"],
"env": {
"PUSHINPAY_TOKEN": "seu_token_aqui",
"PUSHINPAY_ENV": "sandbox"
}
}
}
}
```
### Cursor
Em `~/.cursor/mcp.json` (ou nas configurações de MCP do projeto), use o mesmo bloco acima.
Depois de configurar, peça em linguagem natural: _"Qual meu saldo na PushinPay?"_
## Desenvolvimento
```bash
npm install
npm run build # compila TypeScript -> dist/
npm run dev # roda em watch mode
npm run smoke # teste ponta a ponta: autentica e lê o saldo
npm run inspect # abre o MCP Inspector (UI para testar as tools)
```
Copie `.env.example` para `.env` e preencha `PUSHINPAY_TOKEN` para os testes locais.
## Especificação e Skill (download público)
- [`openapi.yaml`](openapi.yaml) — especificação OpenAPI 3.0 do núcleo PIX da API (cobrança, transação, reembolso, saque, saldo, assinaturas). Importe no Postman/Insomnia ou gere clientes automaticamente.
- [`skill/SKILL.md`](skill/SKILL.md) — Skill para Claude com as regras de uso da PushinPay. O arquivo `.skill` distribuível é essa pasta compactada.
## Segurança
- O token é lido do ambiente e **nunca** é logado.
- Tokens da PushinPay podem ser **atrelados a IP**. Para uso via MCP (máquina do dev, IP dinâmico), gere um token com IP liberado ou use o ambiente sandbox.
- Reporte vulnerabilidades conforme `SECURITY.md`.
## Licença
MIT
TDQS
Scored across 3 tools
Each tool targets a clearly distinct resource and action: balance lookup, single-transaction status lookup by ID, and PIX charge creation. There is no plausible overlap that would cause misselection, and descriptions reinforce the boundaries (e.g. criar_cobranca_pix explicitly tells the agent to prefer webhooks over polling consultar_transacao).
All three names follow a consistent Portuguese verb_noun pattern (consultar_saldo, consultar_transacao, criar_cobranca_pix) in snake_case with no mixed conventions. The vocabulary (consultar for reads, criar for writes) is predictable and readable.
Three tools is lean but each earns its place for a narrow PIX cash-in integration, covering the core read-balance, read-status, and create-charge flows. It sits at the thin end of the acceptable range, since a payments API surface would typically warrant a few more operations.
Core cash-in lifecycle is covered (create charge, check status, check balance), but there are notable gaps: no transaction listing/history, no cancel or refund operation, and no webhook registration or management tool despite webhooks being the recommended confirmation path. Agents hitting those needs would have no tool to call.