Skip to main content
Glama
ALASTecnology

MCP Imposto de Renda

O MCP Imposto de Renda é um servidor MCP (Model Context Protocol) que roda na sua máquina e conversa com o seu cliente MCP via stdio. Ele lê e grava o arquivo de cópia de segurança da declaração (.DBK) do programa oficial, calcula o imposto nos modelos completo e simplificado, explica cada conta, aponta pendências e consulta as tabelas de códigos do exercício. No fim, você restaura o arquivo no programa oficial, confere e transmite por lá.

WARNING

Leia antes de usar.

  • O MCP Imposto de Renda não é serviço oficial da Receita Federal e não tem vínculo com ela nem com qualquer órgão público.

  • Ele não transmite declarações e não acessa sistemas do governo. A entrega é sempre feita pelo programa oficial (PGD).

  • Ele não envia nada pela rede. Porém, tudo o que as ferramentas devolvem ao seu cliente MCP (nomes, CPFs, rendimentos, bens) chega ao provedor de LLM que você escolheu nesse cliente. Leia a política de privacidade desse provedor e decida o que compartilhar.

  • Não há garantia de exatidão. A responsabilidade pela declaração é sempre do contribuinte.

Sumário

Related MCP server: brasilnfe-mcp

Por que usar

  • Você conversa, o assistente preenche. Cole o informe de rendimentos, descreva as despesas e peça para lançar. O servidor acha os códigos certos, grava cada ficha e devolve as pendências na mesma resposta.

  • Cada conta explicada. explicar_calculo mostra a memória de cálculo linha a linha, com a lei aplicada em cada passo: tetos, limites por dependente, truncamento de centavos, comparação entre os modelos.

  • Arquivo do programa oficial, não um formato paralelo. O resultado é um .DBK que o programa da Receita restaura com Ferramentas > Cópia de Segurança > Restaurar. Dá para começar do zero ou partir de uma declaração já iniciada no programa.

  • Conferido contra o programa oficial. O motor reproduz ao centavo 65 casos de referência gerados pelo próprio programa, e o codec regrava byte a byte os arquivos que ele grava.

  • Seus arquivos ficam com você. Sem servidor, conta, telemetria ou conexão de rede. O processo só enxerga a pasta que você autorizar e guarda cópia de cada versão antes de gravar.

  • Software livre e auditável. AGPL-3.0, em TypeScript, sem nenhum código da Receita Federal.

Fluxo da declaração: usuário, cliente MCP, MCP Imposto de Renda local, pasta autorizada e programa oficial

Como é na prática

Trecho real do exemplo 1, com as respostas exatas do servidor. Todos os dados são fictícios; a conversa inteira está em conversa.md.

Você: Este é o meu informe de rendimentos da empresa: rendimentos tributáveis R$ 96.000,00, previdência oficial R$ 9.840,00, imposto retido R$ 11.400,00, 13º salário R$ 8.000,00 com IRRF de R$ 652,30.

O assistente chama adicionar_rendimento_pj com o CNPJ da fonte e os valores, e o servidor responde:

Rendimentos Tributáveis Recebidos de Pessoa Jurídica: item 1 incluído. Gravado 10121874206-IRPF-A-2026-2025-ORIGI.DBK (6 registros).
Cópia do conteúdo anterior: .mcp-imposto-de-renda-backups/10121874206-IRPF-A-2026-2025-ORIGI.DBK.20260410T120000Z.bak.
Controles: conferem.
Sem erros impeditivos; 0 aviso(s).

Você: Qual modelo é melhor para mim? Me mostre a conta.

definir_opcao_tributacao grava o modelo mais vantajoso e explicar_calculo devolve a memória de cálculo (trecho):

Modelo simplificado:
1. Rendimentos tributáveis: R$ 96.000,00 [Mesma soma do modelo completo.]
2. Desconto simplificado: 20% de R$ 96.000,00 = R$ 19.200,00, limitado a R$ 16.754,34; desconto R$ 16.754,34 [Lei 9.250/1995, art. 10, ...]
3. Base de cálculo: R$ 96.000,00 - R$ 16.754,34 = R$ 79.245,66
4. Imposto pela tabela anual (alíquota de 27,50% menos parcela a deduzir de R$ 10.853,78): R$ 10.938,77
...
13. Imposto a restituir: R$ 11.400,00 - R$ 10.938,77, se positivo = R$ 461,23 [Lei 9.250/1995, art. 13.]

Você: Quero receber a restituição por Pix na chave do meu CPF. Confira o arquivo e me diga como entregar.

O servidor grava a opção, confere os controles de integridade (verificar_integridade_arquivo) e devolve o passo a passo para restaurar e transmitir no programa oficial (instruir_transmissao).

Início rápido

Requisito: Node.js 22 ou superior. A versão 0.1.0 ainda não foi publicada no npm; até lá, instale a partir do código (o pnpm vem com corepack enable).

1. Instale e compile.

git clone https://github.com/ALASTecnology/mcp-imposto-de-renda.git
cd mcp-imposto-de-renda
corepack enable && pnpm install && pnpm build
node apps/cli/dist/index.js --versao

2. Crie uma pasta só para a declaração e registre o servidor no seu cliente. No Claude Desktop, por exemplo, em claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-imposto-de-renda": {
      "command": "node",
      "args": [
        "/caminho/para/mcp-imposto-de-renda/apps/cli/dist/index.js",
        "--dir",
        "/Users/voce/Documentos/IR-2026"
      ]
    }
  }
}

Depois da publicação no npm, o comando vira npx -y mcp-imposto-de-renda --dir <pasta>. Opções úteis:

Opção

Efeito

--perfil essencial

90 ferramentas: a declaração inteira, sem os atalhos repetidos por ficha. Use em clientes com limite de ferramentas (VS Code: 128; Windsurf: 100).

--perfil consulta

44 ferramentas: só leitura e cálculo, nada grava.

--grupos e --sem-grupos

Expõem ou tiram grupos inteiros, por nome.

--somente-leitura

Desliga todas as ferramentas que gravam arquivos.

3. Converse. Peça "Vamos preparar a minha declaração do IRPF 2026" ou acione o prompt preparar_declaracao. Para partir do que você já tem, grave a cópia de segurança no programa oficial dentro da pasta e peça para abrir o .DBK.

Mais detalhes em instalação, no tutorial da primeira declaração e em solução de problemas.

Clientes compatíveis

O servidor funciona em qualquer cliente que inicie servidores MCP locais por stdio. O índice de clientes traz o nível de suporte e um guia de configuração para cada um, inclusive os que exigem ponte local ou não são suportados.

Cliente

Suporte

Guia

Claude Desktop

Completo

claude-desktop.md

Claude Code

Completo

claude-code.md

ChatGPT (aplicativo de desktop) e OpenAI Codex

Completo

chatgpt.md, codex.md

Gemini CLI e Antigravity

Completo

gemini-cli.md

GitHub Copilot no VS Code

Completo, com limite de ferramentas do cliente

vscode-copilot.md

Cursor

Completo

cursor.md

Windsurf

Completo, com limite de ferramentas do cliente

windsurf.md

Zed, JetBrains, Cline, Continue, goose, Kiro

Completo

índice

LM Studio e Ollama (modelo local)

Completo

lm-studio.md, ollama.md

Open WebUI

Com ponte local

open-webui.md

Com um modelo rodando na sua máquina (LM Studio, Ollama), nada da declaração sai do computador.

Destaques

Números conferidos no código desta versão (pnpm docs:catalogo e pnpm test).

Indicador

Valor

Onde conferir

Ferramentas MCP

166 em 11 grupos; 100 gravam, 66 com --somente-leitura; perfis essencial (90) e consulta (44)

referência das ferramentas

Casos de referência (golden) reproduzidos ao centavo

65 de 65

packages/core/test/golden/2026, regras do IRPF 2026

Arquivos do programa oficial relidos e regravados byte a byte

96 (48 .DBK e 48 .DEC)

packages/core/test/fixtures/dbk/2026

Tipos de registro do .DBK convertidos para o modelo

57, em 26 fichas

formato do DBK

Regras de validação

108 (81 erros e 27 avisos)

packages/core/src/validate

Tabelas de códigos do exercício

31

tabelas

Funções do programa oficial mapeadas

416: 408 atendidas, 7 parciais, 1 sem equivalente

matriz de cobertura

Testes automatizados

mais de 1.100 testes, em Vitest (o total exato sai de pnpm test)

estratégia de testes

Declarações de exemplo regeneradas a cada teste

4

exemplos

Chamadas de rede

nenhuma (verificado por teste)

segurança

Ferramentas

Mapa dos 11 grupos de ferramentas

Grupo

Ferramentas

O que cobre

ciclo

20

Criar, retificar, copiar, restaurar, fechar e excluir; importar a declaração de 2025, a pré-preenchida, o demonstrativo do GCAP e o Livro Caixa da Atividade Rural; opção de tributação, conta e quotas; importação de informes colados

declaracao

4

Abrir o .DBK/.DEC, converter para o modelo JSON e de volta, gerar o .DEC de conferência

arquivos

5

Listar a pasta e as declarações (em preenchimento e transmitidas), gravar relatório em PDF ou HTML, conferir os controles de integridade e pré-validar o arquivo de entrega como o validador da Receita

fichas

1

Ler uma ficha isolada

edicao

105

Incluir, alterar, remover e listar em 22 fichas em lista, mais as fichas únicas

tabelas

2

Consultar as 32 tabelas de códigos

validacao

2

Pendências da declaração e conferência de CPF, CNPJ, NIT, recibo, CEP, contatos, Renavam e conta bancária

calculo

6

Simular, comparar modelos, explicar o cálculo, quotas, multa e parâmetros

calculadoras

10

Carnê-leão, RRA, preço médio, renda variável, ganho de capital, acréscimos, residência, obrigatoriedade, câmbio

saidas

4

Dados do Darf, relatório, comunicação de saída e passo a passo da transmissão

orientacao

7

Ajuda do programa, atalhos com a ferramenta equivalente, calculadora exata, serviços que só existem fora do servidor, diagnóstico do servidor e modelo de sugestão para o projeto

A referência das ferramentas traz, para cada uma, os parâmetros com tipo e obrigatoriedade, as anotações MCP, um exemplo real de chamada e resposta e as funções correspondentes do programa oficial. Todas são locais (openWorldHint: false); as que gravam são anunciadas com destructiveHint: true, para o cliente pedir confirmação.

Valores monetários na entrada: texto é sempre em reais no formato brasileiro ("1.234,56"); número inteiro é sempre em centavos (123456 = R$ 1.234,56). No modelo JSON da declaração, os valores são inteiros em centavos, as datas em AAAA-MM-DD e CPF/CNPJ só com dígitos.

Tipo

Nome

Para que serve

Prompt

preparar_declaracao

Roteiro guiado de coleta dos informes e preenchimento das fichas, com simulação a cada etapa. Argumento opcional arquivo.

Prompt

revisar_malha_fina

Revisão em busca de pendências e inconsistências que costumam levar à malha fina. Argumento opcional arquivo.

Recurso

mcp-imposto-de-renda://aviso-legal

Limites do servidor: não é serviço oficial, dados vão ao provedor de LLM, revisar e transmitir pelo programa oficial.

Gerado a partir de tools/list do servidor: 166 ferramentas em 11 grupos, 100 delas gravam na pasta autorizada (e somem com --somente-leitura, que deixa 66).

calculo

Simulação do imposto, comparação de modelos, quotas, multa e parâmetros.

Ferramenta

O que faz

Grava?

simular_imposto

Calcula o imposto da declaração (exercício 2026, ano-calendário 2025) nos modelos completo e simplificado e indica o mais vantajoso, com saldo a pagar ou a restituir.

não

comparar_modelos

Compara as deduções legais (modelo completo) com o desconto simplificado de 20% (limitado a R$ 16.754,34) e mostra a diferença de resultado.

não

explicar_calculo

Devolve a memória de cálculo linha a linha, em pt-BR, com a conta feita e a regra legal aplicada em cada passo (rendimentos, deduções, base, tabela progressiva, incentivos, imposto pago, saldo).

não

calcular_quotas

Divide o saldo de imposto a pagar em até 8 quotas (mínimo R$ 50,00 cada; abaixo de R$ 100,00 só quota única), com vencimentos e juros Selic a partir da 2ª quota.

não

calcular_multa_atraso

Multa por atraso (MAED): 1% ao mês-calendário ou fração sobre o imposto devido, mínimo R$ 165,74 e máximo 20%.

não

consultar_parametros

Tabela progressiva anual, limites de dedução, desconto simplificado, prazos e quotas do exercício, com as fontes oficiais.

não

declaracao

Abrir, converter e gravar o arquivo da declaração (DBK/DEC). Exige --dir.

Ferramenta

O que faz

Grava?

abrir_declaracao

Lê um DBK ou DEC da pasta autorizada e devolve um resumo: contribuinte, tipo de declaração, quantidade de itens e totais por ficha, registros por tipo e integridade dos controles.

não

converter_dbk_para_modelo

Converte um DBK/DEC da pasta autorizada no modelo JSON do MCP Imposto de Renda (identificação, dependentes, rendimentos de PJ, pagamentos, bens e dívidas).

não

converter_modelo_para_dbk

Grava a declaração (modelo JSON) em um arquivo .DBK da pasta autorizada.

sim

gerar_arquivo_entrega

Gera o arquivo de entrega (.DEC) a partir de um .DBK da pasta autorizada, montando os registros do recibo (HR, DR e R9) e recalculando os controles, como o programa oficial grava.

sim

fichas

Consulta de fichas da declaração. Exige --dir.

Ferramenta

O que faz

Grava?

ler_ficha

Devolve só uma ficha (identificação, dependentes, rendimentos de PJ, pagamentos, bens ou dívidas) de um DBK/DEC/JSON da pasta autorizada, no formato do modelo (centavos).

não

edicao

Inclusão, edição, remoção e listagem de lançamentos de cada ficha da declaração. Exige --dir.

Fichas em lista: cada uma tem quatro ferramentas. As de inclusão, alteração e remoção validam a declaração e gravam o .DBK com cópia de segurança, devolvendo as pendências.

Ficha

Incluir

Alterar

Remover

Listar

Dependentes

adicionar_dependente

editar_dependente

remover_dependente

listar_dependentes

Alimentandos

adicionar_alimentando

editar_alimentando

remover_alimentando

listar_alimentandos

Rendimentos Tributáveis Recebidos de Pessoa Jurídica

adicionar_rendimento_pj

editar_rendimento_pj

remover_rendimento_pj

listar_rendimentos_pj

Rendimentos Isentos e Não Tributáveis

adicionar_rendimento_isento

editar_rendimento_isento

remover_rendimento_isento

listar_rendimentos_isentos

Rendimentos Sujeitos à Tributação Exclusiva/Definitiva

adicionar_rendimento_exclusivo

editar_rendimento_exclusivo

remover_rendimento_exclusivo

listar_rendimentos_exclusivos

Rendimentos Tributáveis de PJ (Exigibilidade Suspensa)

adicionar_rendimento_exigibilidade_suspensa

editar_rendimento_exigibilidade_suspensa

remover_rendimento_exigibilidade_suspensa

listar_rendimentos_exigibilidade_suspensa

Rendimentos Recebidos Acumuladamente

adicionar_rra

editar_rra

remover_rra

listar_rra

Pagamentos Efetuados

adicionar_pagamento

editar_pagamento

remover_pagamento

listar_pagamentos

Doações Efetuadas

adicionar_doacao

editar_doacao

remover_doacao

listar_doacoes

Doações Diretamente na Declaração

adicionar_doacao_direta_declaracao

editar_doacao_direta_declaracao

remover_doacao_direta_declaracao

listar_doacoes_diretas_declaracao

Bens e Direitos

adicionar_bem

editar_bem

remover_bem

listar_bens

Dívidas e Ônus Reais

adicionar_divida

editar_divida

remover_divida

listar_dividas

Herdeiros/Meeiro

adicionar_herdeiro

editar_herdeiro

remover_herdeiro

listar_herdeiros

Doações a Partidos Políticos e Candidatos

adicionar_doacao_eleitoral

editar_doacao_eleitoral

remover_doacao_eleitoral

listar_doacoes_eleitorais

Demonstrativo de Ganhos de Capital

adicionar_ganho_capital

editar_ganho_capital

remover_ganho_capital

listar_ganhos_capital

Renda Variável: Operações Comuns/Day-Trade

adicionar_renda_variavel

editar_renda_variavel

remover_renda_variavel

listar_renda_variavel

Renda Variável: Operações em FII ou Fiagro

adicionar_fii_fiagro

editar_fii_fiagro

remover_fii_fiagro

listar_fii_fiagro

Demonstrativo da Atividade Rural: Imóveis explorados

adicionar_imovel_rural

editar_imovel_rural

remover_imovel_rural

listar_imoveis_rurais

Demonstrativo da Atividade Rural: Receitas e despesas

adicionar_receita_despesa_rural

editar_receita_despesa_rural

remover_receita_despesa_rural

listar_receitas_despesas_rurais

Demonstrativo da Atividade Rural: Movimentação do rebanho

adicionar_rebanho

editar_rebanho

remover_rebanho

listar_rebanhos

Demonstrativo da Atividade Rural: Bens da atividade rural

adicionar_bem_rural

editar_bem_rural

remover_bem_rural

listar_bens_rurais

Demonstrativo da Atividade Rural: Dívidas vinculadas à atividade rural

adicionar_divida_rural

editar_divida_rural

remover_divida_rural

listar_dividas_rurais

Demais ferramentas do grupo:

Ferramenta

O que faz

Grava?

listar_fichas

Mostra todas as fichas do modelo com a quantidade de itens preenchidos em um DBK/DEC, e quais estão em lista, consultáveis por listar_lancamentos e editáveis pelas ferramentas genéricas de lançamento.

não

listar_lancamentos

Lista os itens de qualquer ficha em lista, com a posição de cada um.

não

editar_lancamento

Altera um item de qualquer ficha em lista (campos mesclados; null remove), valida e grava com cópia de segurança.

sim

remover_lancamento

Remove um item de qualquer ficha em lista, valida e grava com cópia de segurança (dependente ou alimentando com vínculos exige cascata: true).

sim

definir_identificacao

Mescla os campos informados na ficha Identificação do Contribuinte (nome, nascimento, endereço, ocupação, cônjuge, tipo de declaração, retorno ao país, NIT).

sim

definir_rendimentos_pf_exterior

Lança os valores mensais (carnê-leão) de uma pessoa: informe 'mes' e 'valores' (coluna: valor) para um mês, ou 'colunas' (coluna: 12 valores) para o ano.

sim

definir_renda_variavel

Grava o mês (comuns e day-trade por mercado, IRRF de day-trade, IRRF da Lei 11.033 e imposto pago) do titular ou de um dependente; também aceita os valores de janeiro vindos de anos anteriores.

sim

definir_fii_fiagro

Grava o mês das operações com cotas de FII ou Fiagro (resultado líquido, imposto retido e imposto pago) do titular ou de um dependente; 'prejuizo_anterior' informa o prejuízo vindo de anos anteriores.

sim

definir_espolio

Grava a ficha Espólio: 'tipo' ajuste (declaração de ajuste com natureza 81: sobrepartilha e inventariante) ou final (Declaração Final de Espólio: ano do óbito, modalidade, bens a inventariar, decisão judicial ou escritura, inventariante e cônjuge).

sim

definir_saida_definitiva

Grava a ficha Saída Definitiva do País (campos mesclados aos atuais; 'remover': true apaga a ficha).

sim

definir_informacoes_conjuge

Grava a ficha Informações do Cônjuge (campos mesclados aos atuais; 'remover': true apaga a ficha).

sim

definir_receitas_despesas_rurais

Grava as receitas e despesas da atividade rural: na aba brasil, itens { mes, receitaBruta, despesa }; na aba exterior, itens { pais, receitaBrutaMoedaOriginal, despesaMoedaOriginal, resultadoDolar }.

sim

definir_apuracao_rural

Grava os campos digitados da apuração da atividade rural (prejuízo anterior, opção resultado ou limite20, compensação, adiantamentos, limite de 20% no exterior).

sim

definir_rebanho

Grava a movimentação de uma espécie do rebanho (1 a 4 conforme o programa, 5 = outros): estoque inicial, aquisições, nascimentos, consumo e perdas, vendas.

sim

definir_partilha_bem

Na Declaração Final de Espólio, define para um bem (posição em listar_lancamentos com ficha 'bens') se ainda está a inventariar, a situação na data da partilha, o valor de transferência e os percentuais por herdeiro (centésimos: 100,00% = 10000; herdeiros cadastrados em adicionar_herdeiro).

sim

aplicar_caso_especial_bem

Aplica a um bem (posição em listar_lancamentos com ficha 'bens') um caso especial: usufruto (com os CPF/CNPJ dos proprietários ou usufrutuários), bem a inventariar, atualização pela Lei 14.973/2024 ou criptoativo em custodiante; 'desfazer': true desmarca.

sim

buscar_nome_por_documento

Procura, nos DBK/DEC da pasta autorizada, o nome já informado para um CPF ou CNPJ (fontes pagadoras, dependentes, beneficiários de pagamentos e doações).

não

ciclo

Ciclo de vida da declaração (criar, retificar, excluir), opções do Resumo e importações. Exige --dir.

Ferramenta

O que faz

Grava?

importar_declaracao_anterior

Começa a declaração de 2026 com os dados do arquivo de 2025 (DEC gravado para entrega, transmitido ou DBK de cópia de segurança, lido com o leiaute de 2025), como "Importar dados da Declaração de 2025" do programa: Identificação; dependentes e alimentandos; fontes pagadoras de PJ e beneficiários de pagamentos (sem valores); bens e dívidas com situação em 31/12/2024 diferente de zero (o valor passa para a coluna de 31/12/2024); imóveis, bens, rebanho (estoque final como inicial) e dívidas da atividade rural; e o recibo de 2025.

sim

importar_pre_preenchida

Cria a declaração de 2026 a partir do arquivo da pré-preenchida trazido pelo usuário (o DBK ou DEC que o programa oficial grava depois de "Iniciar a partir da Pré-Preenchida" com a conta gov.br Ouro ou Prata).

sim

importar_gcap

Importa na declaração o arquivo que o GCAP 2025 grava em "Exportar para o IRPF2026" (-DDMM-DDMM-GCAP-2025.DEC, um zip com o XML do demonstrativo), como "Importar dados de Ganhos de Capital" do programa: substitui o demonstrativo do mesmo CPF e período e refaz os valores transportados para Rendimentos Isentos (05 pequeno valor, 06 único imóvel, 07 demais reduções, no campo transportado) e Tributação Exclusiva (02 ganho de capital, 03 bens adquiridos em moeda estrangeira, 04 moeda estrangeira em espécie), mantendo o que foi digitado nesses isentos.

sim

importar_livro_caixa_rural

Importa na declaração o arquivo que o programa Livro Caixa da Atividade Rural 2025 grava em "Exportar para o IRPF" (-ARURAL-2025-2025-EXPORTA-IRPF2026.DEC), como "Importar dados da Atividade Rural" do programa: confere o exercício e o controle do arquivo, substitui as receitas e despesas mensais da aba Brasil (as despesas não dedutíveis não entram), grava na Apuração os adiantamentos recebidos e a receita de produtos entregues por adiantamentos anteriores, substitui a linha de cada país da aba Exterior (moeda original) e refaz o isento 15 (resultado não tributável).

sim

fechar_declaracao

Equivalente ao Fechar do programa oficial: espera terminar qualquer gravação em andamento no arquivo (a fila de gravação do servidor), confere os controles do que ficou no disco e informa a última cópia de segurança automática.

não

criar_declaracao

Cria um DBK novo na pasta autorizada a partir da identificação do contribuinte (formato do modelo) e da opção de tributação.

sim

criar_retificadora

Marca a declaração como retificadora com o número do recibo (12 dígitos) da declaração a retificar e grava em um novo DBK (padrão: CPF-IRPF-A-2026-2025-RETIF.DBK), preservando o restante.

sim

registrar_recibo

Guarda o número do recibo (12 dígitos) que o programa oficial mostrou ao transmitir a declaração, num arquivo <declaração>.recibo.json ao lado do DBK/DEC, para preencher uma futura retificadora (criar_retificadora sem 'recibo').

sim

excluir_declaracao

Remove um DBK ou DEC da pasta autorizada, guardando antes uma cópia em .mcp-imposto-de-renda-backups.

sim

gravar_copia_seguranca

Copia um DBK ou DEC da pasta para outro .DBK (um DEC vira DBK sem o recibo, com os controles refeitos).

sim

listar_copias_seguranca

Lista as cópias automáticas guardadas em .mcp-imposto-de-renda-backups (feitas antes de sobrescrever ou excluir), da mais recente para a mais antiga.

não

restaurar_copia_seguranca

Restaura uma cópia de .mcp-imposto-de-renda-backups (nome de listar_copias_seguranca) sobre um .DBK da pasta (padrão: o arquivo de origem; cópia de um .DEC exige arquivo_destino .DBK).

sim

definir_opcao_tributacao

Escolhe deduções legais (completa) ou desconto simplificado, preservando as deduções informadas, e devolve a comparação dos dois modelos com a recomendação.

sim

definir_informacoes_bancarias

Grava a conta para restituição ou débito (banco, agência sem DV, conta, DV, tipo e operação da Caixa), Pix pela chave CPF, número de quotas (1 a 8) e débito automático, validando banco, agência, conta e DV pela regra de cada banco.

sim

definir_imposto_pago

Grava as linhas digitadas da ficha Imposto Pago/Retido: imposto complementar (Darf 0246), imposto pago no exterior e imposto retido na fonte da Lei 11.033/2004.

sim

repetir_valores_bens

Copia a situação em 31/12/2024 para 31/12/2025 nos bens escolhidos (posições de listar_lancamentos com ficha 'bens') ou, sem 'indices', em todos os bens com situação atual zerada; forcar: true copia mesmo quando já há valor.

sim

importar_informe_rendimentos

Lança na declaração o comprovante de rendimentos de PJ colado pelo usuário, em texto ou JSON (sem OCR e sem rede): fonte e CNPJ, quadro 3 (rendimentos, previdência oficial, IRRF), quadro 4 (isentos como parcela de 65 anos, indenizações, lucros), quadro 5 (13º e IRRF do 13º, PLR, aplicações) e plano de saúde do quadro 7.

sim

importar_informe_plano_saude

Lança em Pagamentos Efetuados (código 26) o informe de plano de saúde colado em texto ou JSON: operadora (CNPJ e nome), valor pago por beneficiário e reembolsos.

sim

ler_informe

Lê o comprovante de rendimentos de PJ colado em 'texto' ou num arquivo .txt da pasta autorizada e devolve os campos extraídos por regras fixas (fonte e CNPJ, rendimentos, previdência oficial, IRRF, 13º e IRRF do 13º, isentos e exclusivos), sem gravar nada, sem OCR e sem rede.

não

transferir_excedente_isencao_65

Soma, por beneficiário com 65 anos ou mais em 2025 (contando a partir do mês em que completa 65), a parcela isenta de aposentadoria (isento código 10) de todas as fontes, aplica o limite de R$ 1.903,98 por mês mais o 13º e transfere o excedente para os Rendimentos Tributáveis de PJ da mesma fonte, como a pergunta do programa.

sim

validacao

Validação de CPF, CNPJ, recibo, CEP, contatos, Renavam, conta bancária e pendências da declaração.

Ferramenta

O que faz

Grava?

validar_documento

Confere o formato e o dígito verificador de um campo como o programa oficial faz na digitação.

não

validar_declaracao

Aplica as regras de consistência equivalentes às críticas do programa oficial e lista as pendências: 'erro' impede a entrega, 'aviso' indica risco de malha fina.

não

tabelas

Tabelas de códigos do programa (dependentes, pagamentos, bens, municípios...).

Ferramenta

O que faz

Grava?

listar_tabela

Lista as entradas de uma tabela de códigos do exercício 2026, com filtro opcional por texto (sem diferenciar acentos) e paginação.

não

buscar_codigo

Busca um código exato numa tabela do exercício 2026.

não

arquivos

Arquivos da pasta autorizada. Exige --dir.

Ferramenta

O que faz

Grava?

listar_arquivos

Lista os arquivos .DBK, .DEC, .json e .txt da pasta autorizada (sem subpastas, ocultos ou links).

não

listar_declaracoes

Relação das declarações DBK/DEC da pasta autorizada, como as abas "Em Preenchimento" e "Transmitidas" da tela inicial e a Relação de Declarações do programa: nome, CPF, exercício, tipo (ajuste, final de espólio, saída definitiva), original ou retificadora, modelo (completa ou simplificada) e situação (em preenchimento para DBK, gravada para entrega para DEC, transmitida quando há recibo registrado).

não

gravar_relatorio

Grava na pasta autorizada, em PDF (A4) ou HTML, com layout próprio: o relatório da declaração (arquivo ou declaracao, resumo ou partes como em gerar_relatorio_declaracao, inclusive 'todas' e 'rendimentos_pf') ou um texto em Markdown simples devolvido por outra ferramenta (Darf, comunicação de saída, relação de declarações).

sim

verificar_integridade_arquivo

Confere os controles do arquivo: número de controle (CRC-32) de cada registro, contagens do registro T9 e hash do header.

não

pre_validar_entrega

Reúne num relatório único o que o validador da Receita confere na recepção e que dá para conferir localmente: tipo e exercício do arquivo, número de controle (CRC-32) de cada linha, NR_CONTROLE do header, contagens do T9, NR_HASH do header, NR_HASH do R9 (no .DEC), pendências de erro da validação e totais do Resumo refeitos pelo motor de cálculo.

não

saidas

Etapa final: dados do Darf e passo a passo para transmitir pelo programa oficial.

Ferramenta

O que faz

Grava?

gerar_darf

Calcula os dados do Darf (código de receita, período de apuração, vencimentos e valores de cada quota, juros Selic das quotas e, se informada a data de pagamento após o vencimento, multa de 0,33% ao dia até 20% e juros de mora).

não

instruir_transmissao

Gera o passo a passo e o checklist para concluir no programa oficial da declaração 2026: restaurar o DBK gravado pelo MCP Imposto de Renda, verificar pendências, conferir o Resumo, transmitir com ou sem certificado digital, guardar o recibo e pagar o Darf.

não

gerar_relatorio_declaracao

Monta o relatório da declaração para conferência ou impressão, com layout próprio.

não

gerar_comunicacao_saida

Gera o texto da comunicação de saída definitiva do país, uma por fonte pagadora de rendimentos de PJ, a partir da ficha Saída Definitiva.

não

calculadoras

Calculadoras auxiliares offline: renda variável, preço médio, carnê-leão, RRA, ganho de capital e acréscimos.

Ferramenta

O que faz

Grava?

calcular_carne_leao

Calcula o carnê-leão (Darf 0190) de um mês de 2025 pela tabela progressiva mensal vigente no mês (janeiro a abril pela Lei 14.848/2024; maio a dezembro pela Lei 15.191/2025), com as deduções de previdência oficial, dependentes (R$ 189,59 cada), pensão e livro-caixa, ou o desconto simplificado mensal quando mais vantajoso.

não

calcular_rra

Calcula o imposto do RRA pela tabela progressiva acumulada (tabela mensal do mês do recebimento vezes o número de meses, art.

não

calcular_preco_medio

Calcula o custo médio ponderado por ativo e o resultado de cada venda a partir das notas de corretagem (compras e vendas com custos), separando day-trade (compra e venda do mesmo ativo no mesmo dia), para preencher a Renda Variável.

não

apurar_renda_variavel

Apura o imposto mensal sobre ganhos líquidos: operações comuns 15%, day-trade 20%, FII e Fiagro 20%, com compensação de prejuízos separada por tipo, compensação de IR na fonte (day-trade e Lei 11.033/2004), isenção de ganhos com ações à vista quando as vendas do mês não passam de R$ 20.000,00 e Darf 6015 com vencimento no último dia útil do mês seguinte.

não

calcular_ganho_capital

Simulador de orientação para alienação de imóvel, móvel, participação ou moeda estrangeira em espécie, conferido ao centavo com o GCAP 2025: ganho = valor de alienação menos corretagem e custo; para imóveis, reduções em cascata da Lei 7.713/1988 (aquisição até 1988) e dos fatores FR1/FR2 da Lei 11.196/2005 (meses contados inclusive, percentual com 6 casas, cada redução truncada no centavo); isenções do único imóvel até R$ 440.000,00, da reaplicação em outro imóvel residencial e de pequeno valor (alienações do mês até R$ 35.000,00, inclusive quotas fora de bolsa); alíquotas de 15%, 17,5%, 20% e 22,5% por faixa.

não

atualizar_custo_bem

Orientação e cálculo da atualização do custo de bem ou direito com os valores informados pelo usuário: 'ufir' (bens adquiridos até 31/12/1995, quantidade de UFIR vezes R$ 0,8287, Lei 9.249/1995, art.

não

calcular_acrescimos_moratorios

Calcula a multa de mora (0,33% por dia de atraso, limitada a 20%) e os juros (Selic acumulada informada mais 1% no mês do pagamento) de qualquer débito federal vencido.

não

calcular_condicao_residencia

Determina a data em que a pessoa passa a residente ou não residente no Brasil (IN SRF 208/2002): saída definitiva (não residente na data da saída), ausência temporária (não residente no dia seguinte ao que completar 12 meses fora), retorno de brasileiro ou visto permanente (residente na chegada) e visto temporário (residente ao completar 184 dias no país em 12 meses).

não

verificar_obrigatoriedade

Avalia os critérios de obrigatoriedade da declaração de 2026 (rendimentos tributáveis acima de R$ 35.584,00; isentos e exclusivos acima de R$ 200.000,00; ganho de capital; bolsa acima de R$ 40.000,00; atividade rural; bens acima de R$ 800.000,00; residência; reaplicação de imóvel; exterior e trust) a partir das respostas do usuário.

não

converter_moeda

Converte para reais um valor em moeda estrangeira e explica qual cotação a regra exige para cada finalidade: rendimento ou imposto pago no exterior, dedução, atividade rural, bem ou aplicação financeira (Lei 14.754/2023).

não

orientacao

Orientação sobre serviços que só existem fora do MCP Imposto de Renda (sem acesso à rede).

Ferramenta

O que faz

Grava?

orientar_servico_externo

Explica como usar um serviço que só existe fora do MCP Imposto de Renda (gov.br, pré-preenchida, Carnê-Leão Web, consulta de CPF, e-CAC, extrato e malha, débito automático, Darf e Sicalc, GCAP, Livro Caixa rural, restituição) e o que trazer de volta para a pasta autorizada.

não

obter_ajuda

Devolve a ajuda de uma ficha, demonstrativo, menu ou regra do programa oficial, tirada das notas de mapeamento do MCP Imposto de Renda (onde fica, a quem se aplica, campos, validações, códigos e regras de cálculo, com a página da Ajuda do programa).

não

verificar_versao_tabelas

Informa de qual versão do programa oficial vieram as tabelas de códigos e parâmetros embarcadas no MCP Imposto de Renda e quantos registros cada uma tem.

não

calcular_expressao

Calculadora do MCP Imposto de Renda, equivalente a Ferramentas > Calculadora do programa oficial: avalia expressões com +, -, *, /, parênteses e porcentagem ("27,5% * 10.000,00") em aritmética decimal exata, sem erro de arredondamento binário, e arredonda o resultado (metade para cima) nas casas pedidas.

não

consultar_atalhos

Explica os atalhos de teclado e os botões do programa oficial (barra de ferramentas, menus por Alt, F1, F5, F11 de acessibilidade, Ctrl+P, Ctrl+Shift+G e outros) e diz qual ferramenta do MCP Imposto de Renda faz a mesma coisa, com o status de cobertura.

não

diagnosticar_servidor

Mostra o estado do próprio servidor do MCP Imposto de Renda: versão, versão das tabelas, perfil, grupos e quantidade de ferramentas registradas, se há pasta autorizada (só o nome da pasta, nunca o caminho), modo somente leitura, uso de memória do processo e versões do Node e da plataforma.

não

enviar_sugestao

Monta o texto de uma issue para o repositório público do MCP Imposto de Renda (sugestão, problema ou dúvida), com modelo, versão, perfil e plataforma, e devolve o link para o usuário abrir e enviar ele mesmo.

não

Declarações de exemplo

Quatro declarações fictícias completas, feitas com o próprio servidor. Cada uma traz o roteiro de pedidos, a conversa com as respostas reais, a saída do cálculo e o .DBK pronto para restaurar no programa oficial. A suíte de testes regenera os quatro exemplos e falha se algum byte mudar.

Exemplo

Perfil

Resultado

Assalariado simples

Um empregador, poupança e CDB

Simplificado, restituir R$ 461,23

Família com dependentes

Companheira e dois filhos, plano de saúde, escola, faculdade, imóvel financiado

Completo, restituir R$ 9.572,98

Aposentado com 65 anos ou mais

Duas fontes que informaram a parcela isenta inteira

Simplificado, pagar R$ 5.693,16 em 3 quotas

Autônoma com carnê-leão

Livro-caixa, PGBL e uma clínica que retém imposto

Completo, pagar R$ 4.653,06 em 4 quotas

Arquitetura

Arquitetura do monorepo e regra de dependência

apps/cli        mcp-imposto-de-renda          executável stdio: argumentos, pasta, logs em stderr
packages/mcp    @mcp-imposto-de-renda/mcp     createServer(): 166 ferramentas, prompts, recursos, PastaAutorizada
packages/core   @mcp-imposto-de-renda/core    codec DBK, modelo, conversão, motor de cálculo, validação, tabelas (sem I/O)
exemplos/                                     declarações fictícias geradas pelo servidor
tools/                                        leiaute, harness de referência, mapeamento e geradores de documentação
docs/                                         arquitetura, referência, guias, regras, mapeamento, ADRs

A dependência só vai de fora para dentro e o core não faz I/O. Uma chamada percorre sempre o mesmo caminho: bytes do .DBK, registros de posição fixa, modelo tipado, alteração, validação, registros com o Resumo e os controles recalculados, gravação atômica com backup.

Sequência de uma sessão típica

O detalhamento de cada camada, com diagramas de fluxo e do ciclo de vida da declaração, está em docs/arquitetura.md.

Segurança

Proteções do servidor local

  • Sem rede. O código do servidor e do CLI não importa http, https, net, tls, dns nem child_process e não usa fetch; um teste automatizado confere isso. Só o transporte stdio é oferecido (ADR 0001).

  • Pasta autorizada. Só nomes relativos dentro de --dir. Caminhos absolutos, .., ~, links simbólicos, arquivos ocultos e nomes reservados do Windows são recusados antes de tocar no disco.

  • Gravação segura. Escrita atômica com fsync, cópia automática em .mcp-imposto-de-renda-backups (10 por arquivo, permissão 0600) e --somente-leitura para consultar sem risco.

  • Limites. 20 MB por arquivo e 50.000 elementos por chamada.

  • Logs sem dados pessoais. Só eventos do processo, nome da ferramenta e classe do erro, em stderr. Mensagens de erro nunca levam caminho absoluto nem conteúdo da declaração.

  • Conteúdo marcado como dado. O que vem de arquivo ou de texto colado volta delimitado e identificado como dado da declaração, não instrução, o que reduz o risco de injeção de prompt por um documento.

Modelo de ameaças completo em docs/seguranca.md. Para relatar uma vulnerabilidade, siga o SECURITY.md e nunca abra issue pública com o problema.

Privacidade e LGPD

A declaração reúne dados pessoais, financeiros e, em despesas médicas, dados de saúde, que a Lei Geral de Proteção de Dados (Lei 13.709/2018) trata como sensíveis. O que acontece com eles depende de onde cada parte roda:

Onde

O que acontece com os dados

MCP Imposto de Renda

Roda só na sua máquina. Não coleta, não guarda fora da pasta autorizada, não envia nada e não tem telemetria. O projeto não recebe nenhum dado.

Pasta autorizada

Guarda o .DBK, as cópias de segurança e o recibo registrado. Você controla e apaga quando quiser.

Cliente MCP e provedor de LLM

Recebem tudo o que você digita e tudo o que as ferramentas devolvem. O tratamento segue os termos e a política de privacidade do provedor escolhido.

Programa oficial e Receita Federal

Recebem a declaração quando você a transmite, como em qualquer entrega.

Recomendações práticas:

  • Prefira um provedor que não use as conversas para treinar modelos, ou um modelo local (LM Studio, Ollama), quando a declaração tiver dados de terceiros.

  • Compartilhe só o necessário. Dependentes, alimentandos e prestadores de serviço também são titulares de dados pessoais.

  • Use uma pasta exclusiva para a declaração e --somente-leitura quando só quiser consultar.

  • Apague a conversa no cliente e as cópias em .mcp-imposto-de-renda-backups quando não precisar mais delas.

Esta seção é informativa e não substitui orientação jurídica.

Precisão

Suíte de referência: casos sintéticos, programa oficial local, golden e fixtures

O motor de cálculo e o codec do arquivo são próprios, em TypeScript (ADR 0002). Para saber se estão certos, o projeto compara o resultado com o do programa oficial:

  1. Casos sintéticos em tools/referencia/casos descrevem declarações com CPFs gerados, nomes fictícios e valores escolhidos para isolar uma regra (cada faixa da tabela, tetos, limites, arredondamento, empate entre modelos).

  2. Um harness local (tools/referencia) usa o programa oficial, baixado pelo próprio desenvolvedor e nunca versionado, como biblioteca: preenche as fichas, executa o cálculo oficial e grava o resultado esperado (golden) e os arquivos .DBK/.DEC gravados pelo próprio programa (fixtures).

  3. A suíte de testes exige que o motor reproduza todos os campos de cada golden ao centavo e que o codec releia e regrave cada fixture byte a byte, com os controles de integridade recalculados.

  4. Quando um caso diverge, a regra é investigada e documentada em docs/regras/irpf-2026.md. Foi assim que se confirmou, por exemplo, que o programa trunca a fração de centavo das alíquotas, do desconto de 20% e do limite de 12%.

Nenhum código, classe, binário ou recurso do programa oficial entra no repositório, e nada dele é descompilado. O software publicado nunca executa, embute ou baixa o programa oficial.

Estrutura do arquivo DBK: header, fichas, T9 e controles

O formato do arquivo, com os quatro controles de integridade (CRC-32 por registro, contagens do T9, hash e controle do header), está em docs/formato-dbk.md.

Limitações conhecidas

  • Só o exercício 2026 (ano-calendário 2025). Leiaute, tabelas e motor são versionados por exercício.

  • Arquivo de entrega conferido nos casos de referência. gerar_arquivo_entrega grava o .DEC igual ao do programa nos 65 casos de referência, inclusive o imposto pago de ganho de capital e o imposto da moeda estrangeira em espécie do recibo. A transmissão continua sendo feita pelo programa oficial.

  • Serviços on-line da Receita Federal estão fora de escopo: transmissão, certificado digital, login gov.br, declaração pré-preenchida, Carnê-Leão Web, Darf com código de barras e recibo.

  • Sem leitura de PDF. Informes de rendimentos e de plano de saúde entram como texto ou JSON colado pelo usuário; não há OCR.

  • Cálculo do ajuste com demonstrativos parciais. A atividade rural no Brasil entra no cálculo; RRA pela opção do ajuste, prejuízo rural a compensar, atividade rural no exterior e a Lei 14.754 ficam com os valores do arquivo. Ganho de capital e renda variável são de tributação definitiva e não mudam o ajuste.

  • Limite de ferramentas de alguns clientes. Clientes que aceitam menos de 166 ferramentas precisam de --perfil essencial (90) ou de --grupos; o guia de cada cliente explica como.

  • Pendências documentadas em docs/regras/irpf-2026.md, como a contribuição do ente patrocinador no código 37 e os limites de 6%, 7% e 1% das doações, ainda não confirmados por caso de referência.

Perguntas frequentes

Preciso do programa oficial? Sim, para conferir e transmitir. O servidor prepara o .DBK; a entrega é sempre feita pelo programa da Receita Federal.

Funciona sem internet? O servidor, sim. O cliente MCP precisa de rede se o modelo de linguagem for remoto; com um modelo local, nada sai da máquina.

Posso partir da declaração que já comecei no programa? Sim. Grave a cópia de segurança (Ferramentas > Cópia de Segurança > Gravar) na pasta autorizada e peça para abrir o .DBK. O que o servidor não descreve no modelo é preservado byte a byte na regravação.

E se o assistente lançar algo errado? Toda gravação guarda a versão anterior. listar_copias_seguranca e restaurar_copia_seguranca desfazem a alteração, e editar_* ou remover_* corrigem o lançamento.

O cálculo é igual ao do programa? Nos 65 casos de referência, sim, ao centavo. Fora deles pode haver divergência; o programa oficial é sempre a palavra final.

Mais respostas em docs/guias/perguntas-frequentes.md.

Roadmap

  • IRPF 2027 (ano-calendário 2026), com as mudanças da Lei 15.270/2025: nova tabela anual, redução do imposto do art. 11-A e tributação mínima de altas rendas. Notas em docs/regras/irpf-2027.md.

  • Exercícios anteriores, para retificadoras e declarações em atraso.

  • Importação de PDF local de informes de rendimentos, lida na máquina, sem serviço externo.

  • Publicação no npm, para instalar com npx mcp-imposto-de-renda.

  • As funções do programa oficial ainda parciais na matriz de cobertura, cada uma com a justificativa e a alternativa em uso: a importação do Carnê-Leão Web e da pré-preenchida (serviços autenticados da Receita).

Documentação

O índice da documentação organiza tudo pelo que você quer fazer. Os pontos de partida mais comuns:

Para

Leia

Instalar e configurar o cliente

Instalação e clientes MCP

Fazer a primeira declaração

Tutorial e exemplos

Saber o que cada ferramenta faz

Referência das ferramentas e mapa das fichas

Entender o código

Arquitetura e desenvolvimento

Conferir regras e cálculos

Regras do IRPF 2026 e formato do DBK

Contribuição

Contribuições são bem-vindas. Leia o CONTRIBUTING.md e o Código de Conduta. Duas regras não têm exceção: nenhum código da Receita Federal entra no repositório e nenhum dado real (declaração, CPF, informe) entra em issue, PR ou teste. Divergência de cálculo se reporta com caso sintético, pelo modelo de issue próprio.

pnpm install
pnpm lint && pnpm typecheck && pnpm test && pnpm build
pnpm docs:catalogo && pnpm docs:links   # documentação gerada e links

Licença

AGPL-3.0-only. O motivo da escolha está no ADR 0003. Versões modificadas, inclusive oferecidas pela rede, precisam disponibilizar o código-fonte sob a mesma licença.

O MCP Imposto de Renda é software livre fornecido "no estado em que se encontra", sem garantia de qualquer tipo, nos termos da AGPL-3.0. Não é serviço oficial da Receita Federal do Brasil, não tem vínculo com ela nem com qualquer órgão público e não usa marca, brasão ou identidade visual do governo. Cálculos, conversões e validações podem divergir do programa oficial. Abra o arquivo no programa da Receita Federal, confira cada ficha e transmita por ele. A responsabilidade pelas informações declaradas é sempre do contribuinte. Os dados que você compartilha com o assistente são tratados pelo provedor de LLM escolhido por você, segundo os termos desse provedor.

Related MCP Connectors

Related MCP Servers

  • F
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to help compile the Italian Modello 730 income tax return by providing IRPEF calculations, deduction tools, and tax rule guidance.
    12
    23
    -
  • F
    license
    Not graded
    quality
    F
    maintenance
    MCP server that exposes Brazilian tax infrastructure as tools, resources, and prompts, enabling AI agents to emit and manage fiscal documents (NF-e, NFC-e, NFS-e, CT-e, MDF-e, DC-e) through natural language.
    -
  • F
    license
    Not graded
    quality
    C
    maintenance
    Enables AI assistants to interact with local documents (PDF, Markdown, TXT) through tools for discovery, reading, extraction, summarization, comparison, keyword extraction, search, and analysis, ensuring privacy and offline capability.
    -
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables AI assistants to locally parse, validate, audit, explain, generate, and convert XRechnung and ZUGFeRD/Factur-X e-invoices using official rule sets, fully offline with no API keys required.
    Apache 2.0