kotas-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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
Related MCP server: mcp-upbank
Instalação
Tudo de uma vez (Claude Code)
bun run setupCompila 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-mcpBiná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 localStorageO 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 123456Se 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 csvTodo 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 mcpOu à 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
Variável | Default | Para quê |
|
| Onde ficam sessão, chave e cache |
| — | Chave AES em base64 de 32 bytes; sem ela, uma é gerada em |
|
| O único diretório onde |
|
| Não registra |
|
| Respostas mínimas por padrão, para economizar contexto |
| — | Só para o bootstrap do |
| — |
|
|
| Header |
| (chave do front) | Chave estática da API, igual para todo mundo |
|
| Intervalo mínimo entre requisições |
|
| Variação aleatória somada ao intervalo |
|
| Timeout de cada requisição |
| — | Espelha o log (que sai no stderr) em um arquivo |
|
| Só para testes |
Tools
Tool | Comando | Rede |
|
| 0 (1 com |
|
| 1–2 |
|
| ≈ 6 (3 com |
|
| em blocos |
|
| 0 |
|
| 0 (1 se não estiver no cache) |
|
| 0 |
|
| 0 (1 se faltarem os itens) |
|
| 0 |
|
| 2 |
|
| 0 |
|
| 0 |
|
| 0 |
|
| 1 |
|
| 0 |
|
| 1 |
Referência completa dos parâmetros em docs/TOOLS.md, gerada a
partir do registry.
Como funciona
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.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.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 quepurchase_historyenxerga assinaturas que o site já não mostra.Cache local. SQLite em
~/.config/kotas-mcp/cache.db, com o payload cru guardado ao lado do dado interpretado — assimsync --reparsereprocessa todo o histórico sem gastar uma requisição.
Troubleshooting
Sintoma | O que fazer |
|
|
| Confirme o e-mail/SMS/Telegram e rode |
|
|
| É esperado: chame de novo até |
Listas vazias | O cache está vazio: rode |
HTTP 426 | A versão do front mudou: ajuste |
HTTP 400 em um grupo | O grupo foi encerrado e não existe mais na API; use |
Algo quebrou de um jeito estranho |
|
Documentação
Arquivo | Conteúdo |
Camadas, regras duras e por que cada uma existe | |
Variáveis, arquivos em disco e registro no Claude Code | |
Do zero à primeira pergunta | |
Referência dos comandos | |
Referência das tools (gerada) | |
Os três caminhos de login e o que fica gravado | |
Modelo de domínio e schema do cache | |
A API do Kotas e as armadilhas confirmadas | |
O que fazer quando o Kotas mudar | |
Uma decisão por arquivo | |
O que as fixtures são e o que a anonimização faz |
Licença
MIT. Veja LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Chat with your bank data: balances, transactions, budgets, bills. Reads only, never moves money.
Ask your AI about your own accounts, debts, budgets and goals. OAuth sign-in, read-only by default.
Ask about your Waypoint Budget spending, budgets, goals and accounts. Read-only.
Track subscriptions and renewals from your AI chat: schedules, due dates, reminders, local data.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables querying personal finance data including accounts, transactions, spending, holdings, net worth, and budgets from your self-hosted OpenCoffer instance. Supports natural language queries through any MCP-compatible client.19MIT
- AlicenseNot gradedqualityDmaintenanceEnables querying Up Bank account transactions and spending habits through natural language, using the Up Bank API in read-only mode.9 npm8Do What The F*ck You Want To Public
- AlicenseNot gradedqualityDmaintenanceEnables querying personal finance reports (merchant spending, largest expenses) and performing currency conversion via a local SQLite database.ISC
- FlicenseBqualityCmaintenanceEnables read-only SQL queries and transaction classification tools for local expense tracking, including listing, filtering, and bulk account assignment with dry-run mode.8-