Skip to main content
Glama

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:

  1. Baixe o CalculadoraRTC-Claude-Setup-<versão>.exe na página de Releases.

  2. 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.

  3. Feche o Claude Desktop por completo (ícone perto do relógio → Sair) e abra de novo.

  4. 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.0

O 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-registro

Em desenvolvimento, use python server.py --registrar.

Related MCP server: mcp-fiscal-brasil

Ferramentas

Ferramenta

O que faz

Endpoint da API

calcular_tributos

Calcula CBS, IBS e IS de uma operação; erros por item sem interromper os demais

POST /observabilidade/regime-geral

explicar_erro

Descreve um código de erro do cálculo (ex: REG-011)

GET /observabilidade/erros

calcular_base_calculo_unificada

Base de cálculo unificada da NF-e/NFC-e a partir dos componentes

POST /base-calculo/base-calculo-unificada

listar_situacoes_tributarias

CSTs de CBS/IBS com as cClassTrib vinculadas

GET /dados-abertos/situacoes-tributarias/cbs-ibs

buscar_classificacao_tributaria

cClassTrib por código, CST, atores, DF-e ou busca textual

GET /dados-abertos/classificacoes-tributarias/cbs-ibs/...

validar_nomenclatura_aplicavel

Verifica se uma NCM/NBS é compatível com a cClassTrib

.../ncm-aplicavel, .../nbs-aplicavel

consultar_ncm

Descrição da NCM e se é tributada pelo IS

GET /dados-abertos/ncm

consultar_nbs

Descrição da NBS

GET /dados-abertos/nbs

consultar_aliquotas_referencia

Alíquotas de referência da União, UF e município

GET /dados-abertos/aliquota-*

listar_ufs

UFs com código IBGE

GET /dados-abertos/ufs

listar_municipios

Municípios de uma UF com código IBGE (com busca por nome)

GET /dados-abertos/ufs/municipios

consultar_fundamentacao_legal

Base legal de cada cClassTrib (com busca)

GET /dados-abertos/fundamentacoes-legais

listar_tipos_dfe

Tipos de DF-e (NF-e, NFC-e, NFS-e...) com sigla e modelo

GET /dados-abertos/dfe/grupos

nfse_classificacoes_por_nbs

CST e cClassTrib aplicáveis a um serviço (NFS-e)

GET /nfse/situacoes-classificacoes-tributarias

nfse_local_operacao

Local da operação da NFS-e pelo indicador de operação

GET /nfse/local-operacao

status_conexao

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

GET /dados-abertos/versao

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 DEPRECATED e EXPERIMENTAL, 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/status e /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_DIR para 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:

  1. O Claude conecta no MCP. Aparece um aviso no Windows: "Claude conectado à Calculadora RTC".

  2. 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:run com o perfil offline. Quando a API fica pronta, aparece o aviso "Calculadora RTC pronta". Se uma ferramenta for chamada antes disso, ela espera a API subir.

  3. 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 connection do 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.txt

Registrar 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á

claude_desktop_config.json

App do Claude: chat, menu + → Conectores e aba Code

Pelo app (Configurações → Desenvolvedor → Editar configuração) ou editando o arquivo

~/.claude.json

Claude Code (terminal e aba Code do app)

claude mcp add

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 --registrar

Ele 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-registro

Alternativa: 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.py

No 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

RTC_BASE_URL

http://localhost:8080/api

URL base da API

RTC_HTTP_TIMEOUT

60

Timeout em segundos

RTC_MAX_RESULTS

50

Máximo de itens nas listagens

RTC_AUTOSTART

1

Sobe a API Java sozinho quando ela está parada (só para URL local)

RTC_STOP_ON_EXIT

1

Encerra a API iniciada pelo MCP quando o Claude desconecta

RTC_NOTIFY

1

Mostra avisos do Windows ao conectar, quando a API fica pronta e em caso de falha

RTC_API_DIR

../calculadora-rtc-regime-regular

Pasta do projeto da API

RTC_JAVA_HOME

detecção automática

JDK a usar (senão JAVA_HOME, as instalações em Program Files e o PATH)

RTC_STARTUP_TIMEOUT

180

Segundos de espera pela API subir

RTC_HOME

~/.calculadora-rtc

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 claude mcp add

Rode server.py --registrar (instalação manual) ou o instalador de novo

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 %LOCALAPPDATA%\Programs\Calculadora RTC\mcp\calculadora-rtc-mcp.exe, sem args

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.py

O 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 tools
buscar_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 busca para 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_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

    A3.6/5.0

    Scored across 16 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      Connects AI agents to Brazilian tax compliance data (CNPJ, CPF, NFe, SPED, eSocial) and provides tools for due diligence, risk scoring, and tax regime comparison.
      44
      279 PyPI
      431
      MIT
    • A
      license
      B
      quality
      C
      maintenance
      Enables 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.
      44
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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