calculadora-rtc
This MCP server lets an assistant calculate Brazilian consumption-tax reform taxes (CBS, IBS, Imposto Seletivo) and consult official supporting tables through the calculadora-rtc API.
Calculate CBS, IBS estadual/municipal, and IS for an operation, with independent per-item results and errors.
Explain calculation error codes such as REG-011.
Calculate the unified NF-e/NFC-e CBS/IBS tax base from components by year, nature, and document type.
List CSTs with linked cClassTrib and search/filter cClassTrib by code, CST, actors, DF-e, or text.
Validate whether an NCM or NBS is compatible with a cClassTrib.
Look up NCM and NBS descriptions and Imposto Seletivo applicability.
Consult reference tax rates for União, UF, and municipality.
List UFs and municipalities with IBGE codes and name search.
Consult the legal basis for cClassTrib under LC 214/2025.
List DF-e types with acronym and model.
For NFS-e, list applicable CST/cClassTrib by NBS and determine the place of operation from the operation indicator.
Check MCP/API connection status, database version, logs, and start the Java API if offline.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@calculadora-rtc Calcule CBS e IBS de R$ 100 em Porto Alegre em março de 2027"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
mcp-calculadora-rtc
Servidor MCP para a Calculadora de Tributos da Reforma Tributária do Consumo (CBS, IBS e Imposto Seletivo — LC 214/2025).
Ele envolve a API REST do projeto calculadora-rtc-regime-regular e permite que um assistente (Claude, por exemplo) calcule tributos e consulte as tabelas oficiais em vez de responder de memória:
"Qual cClassTrib uso para venda de arroz? A NCM 10063021 é compatível? Calcule CBS e IBS de R$ 100 em Porto Alegre em março de 2027."
Instalação fácil (Windows)
Para quem só quer usar, sem programar:
Baixe o
CalculadoraRTC-Claude-Setup-<versão>.exena página de Releases.Execute e clique em Avançar até concluir. Não precisa de administrador.
Se o Windows mostrar "O Windows protegeu o computador", clique em Mais informações e depois em Executar assim mesmo. O instalador não tem assinatura digital paga.
Feche o Claude Desktop por completo (ícone perto do relógio → Sair) e abra de novo.
Pergunte ao Claude: "qual o status da calculadora?"
O instalador já traz tudo: o MCP compilado (sem Python), um Java próprio enxuto (sem instalar Java), a API e o banco de dados já gerado. Ele registra a calculadora no app do Claude e, se existir, no Claude Code. Para desinstalar, vá em Configurações do Windows → Aplicativos; a desinstalação remove também o registro no Claude.
A calculadora não apareceu em + → Conectores? Veja Não aparece em Conectores?.
Gerar o instalador
Na máquina de desenvolvimento, com JDK 21, o .venv do projeto e o Inno Setup 6 (winget install JRSoftware.InnoSetup --scope user) instalados:
powershell -ExecutionPolicy Bypass -File installer\build.ps1 -Version 0.2.0O script gera o JAR e o banco da API, se faltarem, cria o Java enxuto com jlink, compila o MCP com PyInstaller e monta o instalador em installer\output\.
Para registrar ou remover manualmente:
calculadora-rtc-mcp.exe --registrar
calculadora-rtc-mcp.exe --remover-registroEm desenvolvimento, use python server.py --registrar.
Related MCP server: mcp-fiscal-brasil
Ferramentas
Ferramenta | O que faz | Endpoint da API |
| Calcula CBS, IBS e IS de uma operação; erros por item sem interromper os demais |
|
| Descreve um código de erro do cálculo (ex: |
|
| Base de cálculo unificada da NF-e/NFC-e a partir dos componentes |
|
| CSTs de CBS/IBS com as cClassTrib vinculadas |
|
| cClassTrib por código, CST, atores, DF-e ou busca textual |
|
| Verifica se uma NCM/NBS é compatível com a cClassTrib |
|
| Descrição da NCM e se é tributada pelo IS |
|
| Descrição da NBS |
|
| Alíquotas de referência da União, UF e município |
|
| UFs com código IBGE |
|
| Municípios de uma UF com código IBGE (com busca por nome) |
|
| Base legal de cada cClassTrib (com busca) |
|
| Tipos de DF-e (NF-e, NFC-e, NFS-e...) com sigla e modelo |
|
| CST e cClassTrib aplicáveis a um serviço (NFS-e) |
|
| Local da operação da NFS-e pelo indicador de operação |
|
| Mostra se o MCP está conectado, o estado da API Java, a versão do banco e o log; sobe a API se estiver parada |
|
Nas ferramentas com data, a data padrão é hoje. As listagens grandes (classificações e fundamentação legal) têm filtro busca, que ignora acentos, e limite de itens, para não estourar o contexto do modelo.
O que ficou de fora (de propósito)
Geração e validação de XML (
/xml/*): payloads grandes e uso de sistema para sistema.POST /regime-geral: coberto pela versão com observabilidade.Endpoints
DEPRECATEDeEXPERIMENTAL, como a base unificada da NFS-e.Endpoints de nicho: pedágio, transferências a entes governamentais, redutores de compra governamental e a família do Imposto Seletivo (
/is,/imposto-seletivo)./versao/statuse/dados-abertos/versao, que são de monitoramento.
Requisitos (instalação manual, para desenvolvimento)
Python 3.10 ou superior.
Java 21 ou superior.
O projeto calculadora-rtc-regime-regular clonado ao lado desta pasta (ou aponte
RTC_API_DIRpara ele), com o banco gerado pelo Flyway, conforme o README de lá.Recomendado: gerar o JAR da API uma vez, para ela subir mais rápido (cerca de 11 s, em vez de uns 40 s com
mvnw):cd calculadora-rtc-regime-regular mvnw.cmd -DskipTests package
Início automático da API
Você não precisa subir a API Java na mão. O ciclo é este:
O Claude conecta no MCP. Aparece um aviso no Windows: "Claude conectado à Calculadora RTC".
Se a API estiver parada, o MCP sobe a API em segundo plano. Ele usa o JAR se existir, senão o
mvnw spring-boot:runcom o perfiloffline. Quando a API fica pronta, aparece o aviso "Calculadora RTC pronta". Se uma ferramenta for chamada antes disso, ela espera a API subir.O Claude fecha ou desconecta. A API que o MCP iniciou é encerrada junto. No Windows, um Job Object garante isso até se o processo do MCP for morto à força, então a API nunca fica órfã ocupando a porta 8080.
Se a API já estiver no ar, iniciada por você ou por outra instância do MCP, ela é reaproveitada e não é encerrada.
Para ver o estado a qualquer momento, peça ao Claude "qual o status da calculadora?". Ele chama status_conexao, que mostra a conexão, o estado da API (online, iniciando, offline ou erro), o PID, o tempo de subida, a versão do banco e o caminho do log.
A saída da API vai para ~/.calculadora-rtc/api.log.
O MCP já aplica a correção do erro
Unable to establish loopback connectiondo Java no Windows: ele usa um diretório temporário curto,~/.calculadora-rtc/tmp.
Instalação manual (desenvolvimento)
git clone https://github.com/bispado/mcp-calculadora-rtc.git
cd mcp-calculadora-rtc
python -m venv .venv
# Windows
.venv\Scripts\pip install -r requirements.txt
# Linux/macOS
.venv/bin/pip install -r requirements.txtRegistrar no Claude
O Claude guarda a lista de MCPs em dois lugares diferentes, e cada parte do Claude lê um deles:
Onde | Quem lê | Como um MCP entra lá |
| App do Claude: chat, menu + → Conectores e aba Code | Pelo app (Configurações → Desenvolvedor → Editar configuração) ou editando o arquivo |
| Claude Code (terminal e aba Code do app) |
|
Um MCP registrado só com claude mcp add funciona nas sessões do Claude Code, mas não aparece em Conectores nem no chat comum do app.
Por isso, o jeito recomendado é este comando, que registra nos dois lugares de uma vez:
.venv\Scripts\python.exe server.py --registrarEle acha sozinho o arquivo certo do app. Esse arquivo muda de lugar conforme a instalação: %APPDATA%\Claude\ no instalador comum, %LOCALAPPDATA%\Claude-Data\... nas versões novas ou a pasta da Microsoft Store. O comando também ignora pastas antigas que o Claude abandonou e mantém o resto do arquivo como está. Na primeira alteração, ele guarda um backup do arquivo original em claude_desktop_config.json.bak-calculadora-rtc.
Depois, feche o Claude por completo (ícone perto do relógio → Sair) e abra de novo. Para desfazer:
.venv\Scripts\python.exe server.py --remover-registroAlternativa: editar o arquivo do app à mão
Abra o arquivo pelo próprio app, em Configurações → Desenvolvedor → Editar configuração. Assim você abre o arquivo certo em qualquer tipo de instalação. Dentro de mcpServers, acrescente:
"calculadora-rtc": {
"command": "C:\\caminho\\mcp-calculadora-rtc\\.venv\\Scripts\\python.exe",
"args": ["C:\\caminho\\mcp-calculadora-rtc\\server.py"],
"env": { "PYTHONIOENCODING": "utf-8" }
}Os caminhos são os da sua máquina, onde você criou o .venv. Não copie os caminhos de outra pessoa. Salve e reinicie o app.
Alternativa: só o Claude Code no terminal
Se você usa apenas o Claude Code pelo terminal:
claude mcp add --scope user calculadora-rtc -- <caminho>/.venv/Scripts/python.exe <caminho>/server.pyNo Linux e no macOS, use .venv/bin/python. Lembre que, desse jeito, a calculadora não aparece no app do Claude.
Configuração
Opcional: copie .env.example para .env e ajuste os valores.
Variável | Padrão | Descrição |
|
| URL base da API |
|
| Timeout em segundos |
|
| Máximo de itens nas listagens |
|
| Sobe a API Java sozinho quando ela está parada (só para URL local) |
|
| Encerra a API iniciada pelo MCP quando o Claude desconecta |
|
| Mostra avisos do Windows ao conectar, quando a API fica pronta e em caso de falha |
|
| Pasta do projeto da API |
| detecção automática | JDK a usar (senão |
|
| Segundos de espera pela API subir |
|
| Pasta do log e do diretório temporário do Java |
Não aparece em Conectores?
Se a calculadora funciona no Claude Code mas não aparece em + → Conectores no app, ela está registrada só no cadastro do Claude Code, e não no do app (veja Registrar no Claude). As causas mais comuns:
Causa | Como resolver |
Foi registrada só com | Rode |
O Claude estava aberto durante a instalação e regravou o arquivo, apagando o registro | Feche o Claude (Sair) e rode o instalador de novo |
O app do Claude foi instalado depois da calculadora | Rode o instalador de novo, com o Claude fechado |
O app não foi reiniciado depois do registro | Feche por completo (Sair, e não só fechar a janela) e abra de novo |
O arquivo do app está num local que o registro não conhece | Abra Configurações → Desenvolvedor → Editar configuração e acrescente a entrada à mão (veja acima). No instalador, o executável fica em |
A empresa bloqueia MCPs locais por política | Fale com o administrador do Claude da sua organização |
Para conferir o que está registrado: no app, Configurações → Desenvolvedor lista os servidores locais e o estado de cada um; no terminal, use claude mcp list.
Teste
python smoke_test.pyO teste sobe o servidor via stdio, como um cliente MCP faria, e chama cada ferramenta. Se a API estiver parada, o MCP a inicia e a encerra no final.
No Claude Desktop, o estado do servidor aparece em Configurações → Desenvolvedor, e o log do MCP fica em mcp-server-calculadora-rtc.log, na pasta de logs do Claude.
Aviso
Este é um projeto independente e não é oficial. Os resultados vêm da API da calculadora e servem para simulação e apoio. Confira sempre a legislação e as orientações oficiais.
Licença
Distribuído sob a licença MIT. Veja o arquivo LICENSE.
Available Tools
16 toolsbuscar_classificacao_tributariaA
Consulta classificações tributárias (cClassTrib) de CBS/IBS.
Escolhe a consulta conforme os filtros informados:
c_class_trib (+ sigla_dfe opcional): detalhe completo de uma cClassTrib (tipo de alíquota, percentuais de redução, crédito, nomenclatura exigida etc.).
cst: todas as cClassTrib de um CST.
fornecedor/adquirente (ATOR_ID) e/ou sigla_dfe: cClassTrib aplicáveis aos atores/DF-e.
nenhum dos acima: lista geral; use
buscapara filtrar por texto (ex: 'medicamento', 'educação', 'alimentação humana').
Args: data: Data do fato gerador (yyyy-MM-dd). Padrão: hoje. c_class_trib: Código da cClassTrib (6 dígitos). cst: Código do CST (3 dígitos). sigla_dfe: Sigla do DF-e (ex: 'NFE', 'NFCE', 'NFSE'). fornecedor: ATOR_ID do fornecedor. adquirente: ATOR_ID do adquirente. busca: Texto para filtrar por código/descrição (listas). limite: Máximo de itens retornados em listas (padrão 50).
Inputs: cst, data, busca, limite, +4 more.
calcular_base_calculo_unificadaB
Calcula a base de cálculo unificada de CBS/IBS da NF-e/NFC-e a partir dos componentes do item.
Mostra o que soma e o que é deduzido (PIS/COFINS, ICMS, ISSQN etc. conforme o ano de transição).
Args: ano_fato_gerador: Ano do fato gerador, ex: 2026. natureza: 'bem' ou 'servico'. tipo_documento: Modelo do documento (55=NF-e, 65=NFC-e). vProd..vISSQN: Valores dos componentes (informe só os que existirem).
Inputs: natureza (required), ano_fato_gerador (required), vII, vIS, +14 more.
calcular_tributosA
Calcula CBS, IBS (estadual e municipal) e Imposto Seletivo de uma operação do regime geral.
Usa o endpoint de observabilidade: cada item é calculado de forma independente e, se um item
tiver erro de entrada, os demais ainda são calculados (o item com problema vem com
estadoItem=INCONSISTENCIA_ENTRADA e a lista de erros). Use explicar_erro para detalhar um código.
Dicas antes de calcular:
Descubra CST e cClassTrib com
buscar_classificacao_tributaria/listar_situacoes_tributarias.Confirme que a NCM/NBS é compatível com a cClassTrib via
validar_nomenclatura_aplicavel.O código do município (IBGE) sai de
listar_municipios.
Args: municipio: Código IBGE do município da operação (7 dígitos), ex: 4314902 (Porto Alegre). itens: Itens da operação. dh_fato_gerador: Data/hora do fato gerador ISO 8601 com fuso, ex: '2027-03-10T10:00:00-03:00'. Se omitido, usa agora. uf: Sigla da UF, ex: 'RS'. tp_doc: Modelo do DF-e de origem (55=NF-e, 65=NFC-e, ...). compra_governamental: Preencha apenas em compras governamentais.
Inputs: itens (required), municipio (required), uf, tp_doc, +2 more.
consultar_aliquotas_referenciaA
Consulta as alíquotas padrão/de referência: CBS (União), IBS estadual (UF) e IBS municipal.
Sempre consulta a da União; a da UF e a do município só se os códigos forem informados. Quando não houver alíquota cadastrada para a data, o item correspondente traz o erro.
Args:
data: Data (yyyy-MM-dd). Padrão: hoje.
codigo_uf: Código IBGE da UF (2 dígitos), ex: 43 (RS). Veja listar_ufs.
codigo_municipio: Código IBGE do município (7 dígitos). Veja listar_municipios.
Inputs: data, codigo_uf, codigo_municipio.
consultar_fundamentacao_legalA
Consulta a fundamentação legal (LC 214/2025) de cada cClassTrib.
Informe c_class_trib para a base legal de uma classificação, ou busca para filtrar por texto.
Args: data: Data (yyyy-MM-dd). Padrão: hoje. c_class_trib: Código da cClassTrib. busca: Texto livre (ex: 'medicamento', 'art. 138'). limite: Máximo de itens (padrão 10; os textos legais são longos).
Inputs: data, busca, limite, c_class_trib.
consultar_nbsB
Consulta uma NBS (código de serviço, sem pontos): descrição e dados de tributação.
Inputs: nbs (required), data.
consultar_ncmA
Consulta uma NCM (8 dígitos, sem pontos): descrição hierárquica e se é tributada pelo Imposto Seletivo.
Inputs: ncm (required), data.
explicar_erroA
Retorna a descrição de um código de erro devolvido pelo cálculo (ex: 'REG-011', 'CAL-001', 'VAL-001').
Inputs: codigo (required).
listar_municipiosA
Lista os municípios de uma UF com o código IBGE (usado no cálculo).
Args: sigla_uf: Sigla da UF, ex: 'RS'. busca: Parte do nome para filtrar (ignora acentos), ex: 'porto alegre'. limite: Máximo de itens (padrão 50).
Inputs: sigla_uf (required), busca, limite.
listar_situacoes_tributariasA
Lista os CSTs de CBS/IBS, cada um com as cClassTrib vinculadas (código e descrição).
Bom ponto de partida para escolher CST + cClassTrib de uma operação.
Args:
data: Data do fato gerador (yyyy-MM-dd). Padrão: hoje.
sigla_dfe: Filtra pelo DF-e (ex: 'NFE', 'NFCE', 'NFSE'). Veja listar_tipos_dfe.
Inputs: data, sigla_dfe.
listar_tipos_dfeB
Lista os tipos de DF-e (NF-e, NFC-e, NFS-e...) com sigla e modelo, agrupados (mercadorias/serviços).
Inputs: data.
listar_ufsA
Lista as UFs com sigla, nome e código IBGE.
Inputs: no named parameters.
nfse_classificacoes_por_nbsB
NFS-e: lista os CSTs e cClassTrib aplicáveis a um serviço (código NBS, sem pontos).
Inputs: nbs (required), data.
nfse_local_operacaoC
NFS-e: indica o local da operação (onde o IBS é devido) a partir do Indicador de Operação.
Args: c_ind_op: Código do Indicador de Operação (6 dígitos). data: Data do fato gerador (yyyy-MM-dd). Padrão: hoje.
Inputs: c_ind_op (required), data.
status_conexaoA
Mostra se está tudo conectado: o MCP ligado ao Claude, a API Java da calculadora (online, iniciando, offline ou erro), a versão do banco de dados e onde ver os logs.
Use quando o usuário perguntar se a calculadora está funcionando, ou quando outra ferramenta falhar por conexão. Se a API estiver parada, ela é iniciada em segundo plano.
Args: iniciar_se_offline: Se a API estiver parada, iniciar em segundo plano (padrão: sim).
Inputs: iniciar_se_offline.
validar_nomenclatura_aplicavelA
Valida se uma NCM (mercadoria) ou NBS (serviço) é compatível com a cClassTrib na data.
Informe ncm OU nbs. Retorna valido: true/false. Evita o erro REG-011 no cálculo.
Inputs: c_class_trib (required), nbs, ncm, data.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Most tools target clearly distinct queries (NCM, NBS, UF, município, alíquotas, fundamentação legal). There is mild overlap between listar_situacoes_tributarias and buscar_classificacao_tributaria, and between nfse_classificacoes_por_nbs and buscar_classificacao_tributaria with sigla_dfe, but the descriptions clarify the intended use. calcular_tributos vs calcular_base_calculo_unificada could also be momentarily confused, though they clearly differ in scope.
13 of 16 tools follow a predictable verb_noun pattern (calcular_, listar_, buscar_, consultar_, validar_, explicar_). Three deviate to noun-first (nfse_classificacoes_por_nbs, nfse_local_operacao, status_conexao), but these are still readable and the nfse_ prefix groups them coherently.
16 tools is slightly above the ideal 3-15 range, but for a complex tax engine covering classification, nomenclature, aliquots, legal basis, and calculation, each tool covers a distinct piece. No tool appears redundant or filler.
The surface covers the full lifecycle of a tax calculation: discovery (CST/cClassTrib), validation (NCM/NBS compatibility), aliquots, base calculation, full calculation, error explanation, legal basis, and connection status. Minor gaps exist around batch/multi-item simulation workflows and no explicit mechanism to persist or compare past calculations.
Maintenance
Related MCP Connectors
Brazilian AI-powered accounting & tax automation: NFS-e invoicing, CBS/IBS tax reform, compliance.
Brazil tax reform simulator for AI (CBS/IBS/IS) on Receita Federal's official open-source code.
Issue Brazilian service invoices (NFS-e Nacional) from your AI, with preview and confirmation.
CBS calculator for AI (Brazil tax reform), running Receita Federal's official open-source code.
Related MCP Servers
- AlicenseBqualityCmaintenanceConnects AI agents to Brazilian tax compliance data (CNPJ, CPF, NFe, SPED, eSocial) and provides tools for due diligence, risk scoring, and tax regime comparison.44279 PyPI431MIT
- AlicenseBqualityCmaintenanceEnables AI assistants and automation tools to query and analyze Brazilian fiscal data, including CNPJ, Simples Nacional, NF-e, NFS-e, SPED, eSocial, tax regime comparison, and supplier risk assessment without requiring API keys.44MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants and business systems to query and validate Brazilian fiscal data and documents, including CNPJ/CPF, Simples Nacional/MEI, NF-e/NFS-e, SPED, eSocial, and supplier compliance, without mandatory API keys. It also supports offline reference tables, tax-regime comparison, due-diligence scoring, and 2026 IBS/CBS reform analysis through composable tools.MIT
- AlicenseNot gradedqualityCmaintenanceEnables calculating Brazil's CBS, IBS (state and municipal) and Selective Tax per item for both the regular regime and Simples Nacional, returning official calculation memory, reference rates and legal basis, and generating or validating IBS/CBS/IS XML groups against the official XSD. It also lets users look up the CST, cClassTrib, NCM, NBS and Simples activity tables and understand official error codes.MIT