kotas-mcp

CLI e servidor MCP para as suas assinaturas compartilhadas no Kotas: grupos, o que você paga em cada um, faturas, créditos, cauções, repasses recebidos como administrador, saldo, economia acumulada e o histórico completo — inclusive das assinaturas que você já encerrou. Tudo em um cache local, para que uma pergunta como "quanto já gastei no Kotas?" seja respondida sem abrir o site.

O Kotas não tem API pública de cliente. Este projeto conversa com a mesma API que o app app.kotas.com.br usa, com a sua própria sessão, somente leitura: nenhuma tool cancela assinatura, saca, paga ou muda um valor.

Sumário

• Instalação

• Login

• Uso — CLI

• Uso — MCP

• Variáveis de ambiente

• Tools

• Como funciona

• Troubleshooting

• Documentação

• Licença

Instalação

Tudo de uma vez (Claude Code)

bun run setup

Compila o binário, instala em ~/.local/bin/kotas, registra o servidor MCP no escopo de usuário do ~/.claude.json e instala a Skill em ~/.claude/skills/kotas-mcp/.

npm

npm install -g @maxwellmezadre/kotas-mcp

Binário único

Baixe o executável do seu sistema na página de releases e ponha no PATH. Não precisa de runtime instalado.

Login

Três caminhos, todos gravando o mesmo session.enc cifrado:

kotas login                              # e-mail e senha (pergunta, ou KOTAS_EMAIL/KOTAS_SENHA)
kotas login --from-browser chrome        # importa a sessão de um navegador já logado (macOS)
kotas login --paste                      # cola os três valores do localStorage

O login do Kotas não tem captcha, então o caminho por senha é HTTP puro e não precisa de navegador. A senha é usada uma vez e nunca é gravada: só ficam os dois tokens e o identificador do dispositivo.

Se a conta tiver verificação em duas etapas, passe o código:

kotas login --pin 123456

Se o Kotas pedir liberação de dispositivo (HTTP 412), ele manda um e-mail, SMS ou mensagem no Telegram. Confirme e rode kotas login de novo — o identificador já foi salvo, então não troque de máquina no meio do processo.

Uso — CLI

kotas sync                    # baixa o histórico para o cache (repete os blocos sozinho)
kotas subscriptions           # as assinaturas que você tem hoje
kotas history                 # tudo que você já assinou, inclusive o que encerrou
kotas spending --by month     # quanto por mês
kotas payouts                 # o que você recebe como administrador
kotas balance                 # saldo e economia acumulada
kotas invoices --status pago --from 2026-01-01
kotas subscription 397075     # plano, rateio, vagas e participantes
kotas export history --format csv

Todo comando aceita --json, que imprime o mesmo objeto que a tool MCP devolve.

Uso — MCP

claude mcp add -s user kotas -- /Users/você/.local/bin/kotas mcp

Ou à mão, no ~/.claude.json:

{
  "mcpServers": {
    "kotas": {
      "type": "stdio",
      "command": "/Users/você/.local/bin/kotas",
      "args": ["mcp"]
    }
  }
}

Use o caminho absoluto: clientes MCP não herdam o PATH do seu shell. Depois é só perguntar: "quanto já gastei no Kotas?", "quais assinaturas eu tenho e quanto pago em cada uma?", "quanto vou receber como administrador este mês?"

Variáveis de ambiente

Tools

Referência completa dos parâmetros em docs/TOOLS.md, gerada a partir do registry.

Como funciona

1. Sessão. Dois tokens JWT (acesso e renovação) mais o identificador do dispositivo, cifrados com AES-256-GCM em ~/.config/kotas-mcp/session.enc, modo 0600. O token de acesso dura 15 minutos e é renovado sozinho.

2. Um funil só. Toda requisição passa por src/core/http.ts, que serializa as chamadas, respeita um intervalo mínimo com jitter, faz backoff em 429/5xx e cuida da renovação do token.

3. Faturas como raiz. Um grupo cancelado some da API, então o histórico é reconstruído a partir da descrição das faturas (Fatura grupo <produto> #<id>). É por isso que purchase_history enxerga assinaturas que o site já não mostra.

4. Cache local. SQLite em ~/.config/kotas-mcp/cache.db, com o payload cru guardado ao lado do dado interpretado — assim sync --reparse reprocessa todo o histórico sem gastar uma requisição.

Troubleshooting

Documentação

Licença

MIT. Veja LICENSE.