@contai-evoluke/mcp-server

@contai-evoluke/mcp-server

Calculadoras fiscais brasileiras para LLMs via Model Context Protocol.

v0.6: ~104 tools — 98 calculadoras (trabalhistas, PJ, impostos, imóveis, finanças, saúde, nichos patrimoniais, investimentos internacionais) + 5 ferramentas de consulta (tabelas INSS/IRRF/SM por mês_ano + busca em base curada de ~30 leis brasileiras core) + 1 Decisão Guiada (decisao_clt_vs_pj — wizard que orquestra 4 calcs e devolve veredicto financeiro CLT vs PJ). Erros estruturados, timeout guard, telemetria opt-in. Roda dentro de Claude Desktop, Cursor, Cline e qualquer cliente MCP — zero dep de rede em runtime, tudo local.

Engine de cálculo é pura, versionada e testada com >95% de cobertura — mesma que roda em calculas.com.br.

Instalação

Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "contai": {
      "command": "npx",
      "args": ["-y", "@contai-evoluke/mcp-server"]
    }
  }
}

Reinicia Claude Desktop. As tools calcular_rescisao_clt, calcular_salario_liquido etc. aparecem na barra de tools.

Cursor

Settings → Cursor Settings → MCP → Add new MCP server:

• Name: contai
• Command: npx -y @contai-evoluke/mcp-server

Cline / Continue / outros

Aponte qualquer cliente MCP que suporte stdio transport para:

npx -y @contai-evoluke/mcp-server

Tools disponíveis (v0.6 — ~96 total)

Trabalhistas (12)

Tool	O que calcula
calcular_rescisao_clt	Rescisão completa (4 tipos: sem justa, pedido, acordo, justa causa). Aplica INSS+IRRF
calcular_salario_liquido	Bruto → líquido com INSS + IRRF + dependentes
calcular_13o_salario	13º proporcional, 1ª e 2ª parcela, descontos
calcular_ferias	Férias + 1/3 constitucional, abono pecuniário
calcular_horas_extras	HE com adicional + DSR reflexo (Súmula TST 172)
calcular_horas_extras_dsr	Granular: HE 50% (dia útil) e 100% (DSR/feriado) separados
calcular_fgts_acumulado	Saldo FGTS ao longo do tempo (8% + rendimento + 13º)
calcular_adicional_noturno	Urbano 22h-5h, +20%, hora reduzida 52min30s. Rural variantes
calcular_aviso_previo	30 dias + 3/ano até 90 (Lei 12.506)
calcular_inss_facultativo	5% / 11% / 20% — autônomo, dona de casa, MEI complementar
calcular_insalubridade_periculosidade	Compara excludentes (NR-15 × NR-16)
calcular_seguro_desemprego	Faixas 2026 + carência + nº parcelas

PJ / tributos empresariais (4)

Tool	O que calcula
calcular_mei_das	DAS-MEI mensal (5% SM + ICMS/ISS)
calcular_simples_nacional	DAS Simples (5 anexos + Fator R)
calcular_lucro_presumido	IRPJ + CSLL + PIS/COFINS + ISS/ICMS trimestral
calcular_comparador_regime_tributario	MEI × Simples × LP, recomenda o melhor regime

Imóveis (2)

Tool	O que calcula
calcular_financiamento_imobiliario	SAC vs PRICE, parcelas, total de juros
calcular_itbi	Imposto municipal de transmissão (com regra SFH)

Impostos (2)

Tool	O que calcula
calcular_irpf_restituicao	Compara modelo completo × simplificado, melhor opção
calcular_itcmd	Herança/doação por estado

Veículos (1)

Tool	O que calcula
calcular_ipva	IPVA por UF/tipo, com desconto à vista

Finanças (3)

Tool	O que calcula
calcular_juros_compostos	VF com aportes mensais
calcular_simulador_aposentadoria	FIRE-style, renda perpétua via taxa de retirada
calcular_consorcio_vs_financiamento	Decisão entre os dois pra um bem

Saúde (2)

Tool	O que calcula
calcular_imc	Peso/altura² + classificação OMS
calcular_calculadora_gestacional	Idade gestacional + DPP (Naegele modificada)

Consulta (5)

Tool	O que faz
consultar_tabela_inss_irrf	Faixas oficiais INSS+IRRF 2026 numa chamada
consultar_salario_minimo	Retorna SM nacional vigente + valor anual + fonte legal
consultar_inss_vigente	Faixas progressivas + alíquotas + teto + dedução dependente
consultar_irpf_tabela	Faixas IRRF + dedução por dependente + redutor Lei 15.270/25
buscar_lei	Busca em base curada de ~30 leis BR core (CLT, CTN, CF, LC 123, Lei 9.250 IRPF, etc.). Retorna ementa, link planalto, artigos chave

Decisões Guiadas (1) — engine layer 4

Orquestram 3-7 calcs existentes e devolvem veredicto financeiro com breakdown auditável. ADR-017 documenta a arquitetura.

Tool

O que faz

decisao_clt_vs_pj

Wizard CLT × PJ — vale a pena trocar? Combina salário líquido CLT (com benefícios), simula impostos PJ (Simples Anexo III/V ou Lucro Presumido), pró-labore, distribuição de lucros (isenta — Lei 9.249/95), FGTS perdido, INSS facultativo opcional. Retorna verdict ('CLT'/'PJ'/'TIE'), deltaAnualCents, breakdown completo, riscos qualitativos (sem FGTS, sem 13º, pejotização). Fonte: CLT, LC 123/2006, Lei 9.249/95 art. 10.

Próximas Decisões planejadas (Q3+ 2026): decisao_compro_ou_alugo, decisao_quanto_aposentar, decisao_devo_abrir_empresa.

Todos os valores monetários em centavos (integer) internamente, retornados também formatados em BRL.

Exemplos de uso

"Calcula minha rescisão"

Usuário: "Fui demitido sem justa causa. Entrei em março de 2022 ganhando
         R$ 4.500. Saí ontem (22/abril). Quanto vou receber líquido?"

Claude (usando calcular_rescisao_clt):
{
  "tipo": "sem_justa_causa",
  "salarioBrutoCents": 450000,
  "admissao": "2022-03-01",
  "demissao": "2026-04-22"
}
→ R$ 17.842,35 líquido. Breakdown: saldo R$ 667, aviso indenizado
  R$ 4.500, 13º proporcional R$ 1.500, férias R$ 5.625, multa FGTS 40%
  R$ 5.900, menos INSS R$ 180 e IRRF R$ 170.

"Quanto guardar pra aposentar aos 60?"

Usuário: "Tenho 30 anos, quero aposentar aos 60 com R$ 2 milhões
         guardados. Quanto preciso aportar por mês a 0.8% ao mês?"

Claude (usando calcular_juros_compostos):
{ "capitalInicialCents": 0, "aporteMensalCents": ???,
  "taxaMensalPercent": 0.8, "prazoMeses": 360 }
→ Itera até achar que R$ 1.040/mês dá R$ 2.003.500 em 30 anos.

"Compara SAC vs PRICE"

Usuário: "Imóvel R$ 500k, entrada R$ 100k, 360 meses a 10.49% a.a.
         Qual sistema compensa?"

Claude (duas chamadas):
  SAC   → primeira R$ 4.600, última R$ 1.400, total R$ 680k
  PRICE → parcela fixa R$ 3.660, total R$ 1.320k
→ "SAC economiza R$ 640k ao longo de 30 anos. Parcela inicial é 25%
   mais alta mas total pago é metade."

Preço & uso

Open source / free tier

Grátis, sem limite, sem registro. A engine é livre (MIT). Download via NPM, roda local.

Pro (Q2 2026 — em breve)

Quando o tráfego orgânico crescer, plano Pro incluirá:

• ✅ Todas as +100 calcs do Contaí (não só as 5 iniciais)
• ✅ Remote mode (não precisa rodar NPM local — chamada vai direto pra API do Contaí)
• ✅ Cache de resultado por LLM session
• ✅ Tabelas atualizadas automaticamente (INSS/IRRF mudam → atualização global sem precisar npm update)
• ✅ Support direto, SLA

Inscreva-se em calculas.com.br/mcp-early-access pra saber quando abrir.

Reliability (v0.4)

O servidor expõe garantias claras pra LLM clients:

Erros estruturados

Em vez de throw nu, falhas viram envelope:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "salarioBrutoCents: must be positive",
    "details": { "path": ["salarioBrutoCents"], "cause": "must be positive" }
  }
}

Catálogo de codes:

Code	Quando
INVALID_INPUT	Args não passam no schema Zod
UNKNOWN_CALC	Tool name não existe no registry
RATE_NOT_AVAILABLE	Tabela fiscal/lookup ausente para o período pedido
SCHEMA_DRIFT	Output do engine não bate com schema esperado
INTERNAL	Bug ou exceção inesperada
TIMEOUT	Handler ultrapassou o limite

Timeout

Default 5s por chamada. Configurável via env:

export CONTAI_TIMEOUT_MS=10000  # 10s, faixa 10-60000

Excedeu = { ok: false, error: { code: "TIMEOUT", ... } }. Cliente LLM pode retry ou cair pra fallback.

Semver policy

• patch (0.4.x) — bugfixes, sem mudança de contrato
• minor (0.x.0) — novas tools, novos campos opt-in em outputs existentes
• major (x.0.0) — breaking changes em inputs/outputs, com migration guide

Telemetria (opt-in)

Default OFF (LGPD). Para ligar:

export CONTAI_TELEMETRY=1

Manda apenas:

{
  "tool": "calcular_rescisao_clt",
  "durationMs": 12,
  "ok": true,
  "version": "0.4.0",
  "ts": "2026-04-26T12:00:00Z",
  "installId": "inst_a3f7b2c9"
}

Nunca envia inputs, outputs, IP, email, ou qualquer dado do usuário. installId é random por processo (não persiste). Endpoint configurável via CONTAI_TELEMETRY_URL.

Por que ligar? Ajuda a priorizar bugs em tools menos populares + melhorar latência. Por que não ligar? Privacidade total — qualquer ambiente regulado.

Desenvolvimento

git clone https://github.com/lfhillesheim/calculadora
cd calculadora
pnpm install
pnpm --filter @contai-evoluke/mcp-server dev

Para testar localmente:

{
  "mcpServers": {
    "contai-dev": {
      "command": "node",
      "args": ["/caminho/para/calculadora/packages/mcp-server/dist/index.js"]
    }
  }
}

Publish workflow (npm + MCP Registry)

Para publicar uma nova versão ao npm e ao MCP Registry oficial (registry.modelcontextprotocol.io):

# 1) Bump da versão em package.json + server.json (sincronizado).
# 2) Atualizar CHANGELOG.md.
# 3) Build + publish npm:
cd packages/mcp-server
pnpm build
npm publish --access public

# 4) Instalar mcp-publisher (uma vez):
# macOS/Linux:
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" \
  | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/

# Windows (PowerShell):
#   $arch = if ([Runtime.InteropServices.RuntimeInformation]::ProcessArchitecture -eq "Arm64") { "arm64" } else { "amd64" }
#   Invoke-WebRequest -Uri "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_windows_$arch.tar.gz" -OutFile mcp-publisher.tar.gz
#   tar xf mcp-publisher.tar.gz mcp-publisher.exe
#   # Mova mcp-publisher.exe para um diretório no PATH (ex.: %USERPROFILE%\.local\bin)

# 5) Login com GitHub OAuth (interativo — device flow):
mcp-publisher login github

# 6) Publish ao Registry (rodar dentro de packages/mcp-server, onde está server.json):
mcp-publisher publish

O namespace io.github.lfhillesheim/contai-mcp-server é validado contra o GitHub username do owner — o login GitHub deve ser do @lfhillesheim para passar a verificação de ownership.

Contribuição

Issues em github.com/lfhillesheim/calculadora/issues.

Áreas quentes para contribuir:

• Mais tools: IPVA, ITBI, ITCMD, INSS contribuinte, simples nacional
• Output formats: tabelas markdown, gráficos ASCII
• i18n: tools em inglês (calculate_*) como aliases

Licença

MIT © Calculas / Evoluke 2026