███████╗██████╗ ███████╗████████╗███████╗
   ██╔════╝██╔══██╗██╔════╝╚══██╔══╝██╔════╝
   █████╗  ██████╔╝█████╗     ██║   █████╗
   ██╔══╝  ██╔══██╗██╔══╝     ██║   ██╔══╝
   ██║     ██║  ██║███████╗   ██║   ███████╗
   ╚═╝     ╚═╝  ╚═╝╚══════╝   ╚═╝   ╚══════╝
            C E N T E R   ·   M C P

@andrehocsis/frete-mcp

Frete urbano brasileiro como ferramenta nativa do Claude.

Cote, rastreie e contrate entregas TURBO direto do prompt. Sem SDK, sem boilerplate, sem ler doc.

Quickstart · Tools · Demo · Docs

✨ Por quê?

Você abre o Claude pra resolver um problema de logística. Você precisa:

❌ ler a documentação · achar o endpoint · escrever fetch · parse JSON · tratar erro · console.log · debugar · …

Com @andrehocsis/frete-mcp, a história fica:

Você: Tem motoboy disponível perto do CEP 04543907?
Claude: 🚗 4 motoristas online · mais próximo a 0,8 km · ETA 3 min
        João Silva · CAR · 1.2 km
        Maria Souza · MOTORCYCLE · 0.8 km
        ...

Você: Quanto custa um TURBO de Av. Paulista pra Vila Olímpia?
Claude: R$ 34,38 · entrega em até 3 horas · 3,5 km

Claude vira seu ops manager. Você vira o estrategista.

🚀 30 segundos

# Não precisa clonar nada. npx busca a versão mais recente.
npx -y @andrehocsis/frete-mcp@latest

Cole no seu config do Claude:

{
  "mcpServers": {
    "frete-center": {
      "command": "npx",
      "args": ["-y", "@andrehocsis/frete-mcp@latest"]
    }
  }
}

{
  "mcpServers": {
    "frete-center": {
      "command": "npx",
      "args": ["-y", "@andrehocsis/frete-mcp@latest"]
    }
  }
}

{
  "command": "npx",
  "args": ["-y", "@andrehocsis/frete-mcp@latest"]
}

Reinicia o cliente. Pergunta qualquer coisa de frete. Done.

🎬 Demo

You: Compare 5 entregas TURBO vs EXPRESS de SP pra cinco bairros diferentes
     e me dá um resumo do quanto economizo indo de EXPRESS.

Claude: [chama frete_cotar 10 vezes em paralelo]

        Rota                          TURBO    EXPRESS  Economia
        ─────────────────────────────────────────────────────────
        Paulista → Vila Olímpia       R$ 34   R$ 31    R$ 3 (8%)
        Pinheiros → Moema             R$ 42   R$ 37    R$ 5 (12%)
        Santana → Tatuapé             R$ 56   R$ 49    R$ 7 (12%)
        Itaim → Brooklin              R$ 38   R$ 33    R$ 5 (13%)
        Lapa → Saúde                  R$ 71   R$ 62    R$ 9 (12%)
        ─────────────────────────────────────────────────────────
        Total economia indo EXPRESS:  R$ 29 (~12%)

        Recomendação: para coletas que aguentam 12h, EXPRESS economiza ~12%
        em média. TURBO só vale a pena pra urgências reais (<3h).

You: Roda um cron Python que monitora meus pedidos abertos e me avisa
     no Slack quando alguém entrega.

Claude: [usa frete_meus_pedidos pra entender a estrutura, lê /docs, escreve o cron com webhooks]

        Pronto. Salvei em ./monitor.py com:
        - Polling a cada 5min
        - Cache de IDs já notificados (~/.frete_seen.json)
        - Webhook Slack via env SLACK_WEBHOOK_URL
        Rode com: python monitor.py

You: Implementa um botão "Calcular frete" nesta página HTML
     [cola index.html] que chama frete-center pro CEP do cliente.

Claude: [escreve o JS direto, sem você ter que abrir doc nenhuma]

🛠️ Tools

| Tool | Descrição | Auth | |---|---|---| | 🚚 frete_cotar | Cotação Lalamove com tier TURBO (3h) ou EXPRESS (12h) entre dois CEPs. Retorna preço, distância, ETA. | público | | 📍 frete_motoristas_proximos | Lista motoristas online em raio de N km. Coords com jitter ~300m por privacidade LGPD. | público | | 📦 frete_tracking | Status atual + URL pública de tracking + URL de etiqueta A6 imprimível. | público | | 📊 frete_snapshot | Snapshot agregado: drivers online, distâncias proprietárias cacheadas, blog, rotas SEO. | público | | 💼 frete_meus_pedidos | Lista pedidos do tenant autenticado. | Bearer | | 💰 frete_carteira | Saldo + extrato detalhado da carteira. | Bearer |

Tools que dizem "público" funcionam sem nenhuma credencial. Você só precisa de auth pra coisas que mexem na sua conta.

⚙️ Configuração

| Env | Obrigatória | Descrição | |---|---|---| | FRETE_API_BASE | não | URL base. Default: https://frete.center | | FRETE_API_KEY | opcional | API key server-to-server | | FRETE_BEARER | opcional | JWT user-scoped (alternativa à API key) |

Pra autenticadas, gere sua chave em dev.frete.center/api-keys.

{
  "mcpServers": {
    "frete-center": {
      "command": "npx",
      "args": ["-y", "@andrehocsis/frete-mcp@latest"],
      "env": {
        "FRETE_BEARER": "eyJhbGciOiJIUzI1NiI..."
      }
    }
  }
}

🧭 Por que isso existe

A frete.center é uma camada de logística brasileira (TURBO 3h, marketplace de TACs, auditoria de pedágio, CT-e). Tem API REST, OpenAPI 3.0, webhooks — tudo certinho.

Mas pra integrar com Claude você ainda precisa escrever cliente HTTP, manter tipos, tratar auth, etc.

Este MCP server faz tudo isso virar uma tool nativa do Claude — como filesystem, web search ou git já são. Você fala em português, Claude sabe que existe frete_cotar e usa.

"MCP é o USB-C do AI." — quem entendeu, instala.

🏗️ Self-host / desenvolvimento

git clone https://github.com/andrehocsis/frete-mcp
cd frete-mcp
npm install
npm run dev      # roda direto do TS via tsx
npm run build    # gera dist/

Aponte seu Claude pro build local pra testar mudanças:

{
  "mcpServers": {
    "frete-center-dev": {
      "command": "node",
      "args": ["/caminho/absoluto/dist/index.js"]
    }
  }
}

🗺️ Roadmap

• [x] 6 tools read-only (cotação, drivers, tracking, snapshot, pedidos, carteira)
• [x] Bearer JWT + API key
• [x] Stdio transport (Claude Code, Desktop, Cursor)
• [ ] Tool frete_criar_pedido (write — atrás de confirmação explícita)
• [ ] Tool frete_etiqueta_pdf (gera etiqueta A6 imprimível)
• [ ] Tool frete_publicar_rfq (embarcador publica carga TAC própria)
• [ ] Tool frete_audit_pedagio (audit CT-e × extrato operadora)
• [ ] Resources MCP (rotas SEO, glossário, docs como contexto consultável)
• [ ] Prompts MCP pré-construídos ("/cotar", "/auditar")
• [ ] HTTP transport (pra hospedar como serviço remoto)
• [ ] Streaming responses (entrega em tempo real conforme tools rodam)

PRs bem-vindos. Issues também. Reclamações construtivas, especialmente.

🤝 Contribuindo

1. Issue antes de PR (combinemos o approach pra você não perder tempo)
2. npm run build deve passar
3. Adicione testes pra novas tools (em src/__tests__/)
4. Mantenha o schema simples — apps fora do BR também usam

📜 Licença

MIT — use, fork, melhore, monetize. Só não venda como seu sem dar crédito (você sabe o nome disso).

💬 Suporte

• 📧 [email protected]
• 🌐 dev.frete.center
• 🐙 GitHub Issues

Curtiu? ⭐ Estrela ajuda a gente a saber que o esforço vale.

Feito por frete.center — a camada de logística brasileira que faltava no Claude.