Bling MCP Pro 🔒

Servidor MCP open source para integração segura com a API do Bling ERP

Permite que assistentes baseados em LLM (Claude, etc.) acessem e manipulem dados do Bling ERP através do Model Context Protocol.

⚠️ Projeto não oficial. Não somos afiliados ao Bling Sistemas Ltda.

---

🆕 Melhorias sobre o bling-mcp original

Este projeto é um fork hardened do bling-mcp v1.0.1, com foco em segurança:

Aspecto	Original	Pro
Logs com tokens vazando	❌ Sim	✅ Redação automática
Validação de config	❌ Mínima	✅ Reforçada (HTTPS, formato, tamanho)
Rate limiting	❌ Não tem	✅ Token bucket configurável
Tratamento de erros	❌ Genérico	✅ Mensagens por status HTTP
Transporte HTTP/SSE	❌ Comentado	✅ Funcional
Encerramento limpo	❌ Não tem	✅ SIGINT/SIGTERM
Timeout em requisições	❌ Não tem	✅ 30s padrão
Documentação	❌ Incompleta	✅ Completa
Política de segurança	❌ Não tem	✅ SECURITY.md

---

📦 Funcionalidades

45+ ferramentas MCP cobrindo:

• 📦 Produtos: listar, obter, criar, atualizar, excluir (individual e em lote)
• 👥 Contatos: CRUD completo + tipos + consumidor final
• 💰 Contas a Pagar: CRUD + baixa de conta
• 💵 Contas a Receber: CRUD + baixa de conta
• 🏷️ Categorias: produtos e receitas/despesas
• 💳 Formas de Pagamento: CRUD completo
• 👔 Vendedores: listar e obter
• 📊 Contas Contábeis: listar

---

🚀 Instalação

Pré-requisitos

• Node.js 18 ou superior
• Token de acesso à API do Bling (como obter)

Passo a passo

# 1. Clone o repositório
git clone https://github.com/marlo01/bling-mcp-pro.git
cd bling-mcp-pro

# 2. Instale as dependências
npm install

# 3. Configure o ambiente
cp .env.example .env
# Edite .env e adicione seu BLING_TOKEN

# 4. Compile
npm run build

# 5. Execute
npm start

---

⚙️ Configuração

Todas as configurações são feitas via variáveis de ambiente. Veja .env.example para a lista completa.

Mínimo necessário

BLING_TOKEN=seu_token_aqui

Recomendado para produção

BLING_TOKEN=seu_token_aqui
BLING_CLIENT_ID=seu_client_id
BLING_CLIENT_SECRET=seu_client_secret
BLING_REFRESH_TOKEN=seu_refresh_token
LOG_LEVEL=info
RATE_LIMIT_PER_SECOND=3

---

🔌 Integração com Claude

Claude Desktop (modo stdio)

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "bling": {
      "command": "node",
      "args": ["/caminho/absoluto/para/bling-mcp-pro/dist/index.js"],
      "env": {
        "BLING_TOKEN": "seu_token_aqui",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Claude Web / Remoto (modo HTTP/SSE)

Para usar como Custom Connector remoto, o servidor agora exige autenticação Bearer obrigatória (desde v2.1.0).

1. Gere um token forte (mínimo 32 caracteres)

# Linux / macOS
openssl rand -hex 32

# Windows (PowerShell)
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Max 256) })

# Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

2. Configure as variáveis de ambiente

# No seu servidor (VPS, Docker, etc.)
export BLING_TOKEN=seu_token_bling
export MCP_TRANSPORT=sse
export MCP_PORT=4545
export MCP_AUTH_TOKEN=cole_o_token_gerado_acima
npm start

Sem MCP_AUTH_TOKEN (ou com menos de 32 caracteres) o servidor recusa iniciar em modo de rede.

3. Configure o proxy reverso com HTTPS

Sempre coloque atrás de Nginx/Caddy/Traefik com TLS — o MCP_AUTH_TOKEN viaja no header e precisa de criptografia em trânsito.

4. Adicione no Claude

Settings → Connectors → Add custom connector

• URL: https://seu-servidor.com/sse
• Header: Authorization: Bearer cole_o_token_gerado_acima

Em ferramentas que enviem o header automaticamente (curl, fetch, etc.) o formato é:

curl -H "Authorization: Bearer SEU_MCP_AUTH_TOKEN" https://seu-servidor.com/sse

⚠️ Importante:

• Nunca commite MCP_AUTH_TOKEN no Git.
• Rotacione o token periodicamente (mensalmente).
• Use um valor diferente de BLING_TOKEN — eles têm propósitos distintos.

---

🔒 Segurança

Leia SECURITY.md para detalhes sobre:

• Boas práticas de configuração
• Como reportar vulnerabilidades
• Práticas de segurança aplicadas

Resumo rápido:

• ✅ Tokens nunca aparecem em logs (exceto em LOG_LEVEL=debug)
• ✅ HTTPS obrigatório
• ✅ Rate limiting embutido
• ✅ Validação de configuração na inicialização

---

💖 Apoie o projeto

Este é um projeto open source mantido voluntariamente. Se ele te ajuda, considere:

• ⭐ Dar uma estrela no GitHub
• 🐛 Reportar bugs e sugerir melhorias
• 🤝 Contribuir com código (PRs são bem-vindos!)
• ☕ Fazer uma doação via [PIX/Ko-fi/GitHub Sponsors] (configure em .github/FUNDING.yml)

Não oferecemos suporte técnico individual. Use as Issues do GitHub para a comunidade ajudar.

---

🤝 Contribuindo

Contribuições são muito bem-vindas! Por favor:

1. Abra uma issue antes de PRs grandes
2. Mantenha o código limpo e tipado
3. Não adicione console.log — use logger
4. Não exponha dados sensíveis em logs ou erros
5. Atualize o README se mudar comportamento

---

📜 Histórico

Este é um fork derivativo do bling-mcp v1.0.1, publicado sob licença MIT em abril de 2025 por autor anônimo. Mantemos a atribuição original na LICENSE.

---

⚖️ Aviso legal

• Este software é fornecido "como está", sem garantias.
• Use por sua conta e risco.
• Não somos afiliados ou endossados pelo Bling Sistemas Ltda.
• "Bling" é marca registrada de seus respectivos donos.
• Não somos responsáveis por danos decorrentes do uso deste software.

---

📄 Licença

MIT — sinta-se livre para usar, modificar e distribuir.