Servidor MCP

Servidor MCP Fiscal Brasil.

Registra todas as ferramentas fiscais e expõe via protocolo MCP (Model Context Protocol).

tool_consultar_cnpj async

tool_consultar_cnpj(cnpj)

Consulta o cadastro completo de uma empresa brasileira pelo CNPJ.

Recupera os dados publicos da pessoa juridica na Receita Federal (via BrasilAPI/ReceitaWS): razao social, nome fantasia, endereco, situacao cadastral, natureza juridica, porte, capital social, CNAE principal e secundarias e quadro de socios e administradores (QSA). Util para identificar empresas, validar fornecedores/clientes e preencher dados fiscais.

Parameters:

Name	Type	Description	Default
cnpj	str	Numero do CNPJ com 14 digitos, com ou sem formatacao (ex.: "11.222.333/0001-81" ou "11222333000181").	required

Returns:

Type	Description
dict[str, Any]	dict com os dados cadastrais completos da empresa.

tool_listar_cnpjs_por_nome async

tool_listar_cnpjs_por_nome(nome, uf=None)

Busca empresas pelo nome empresarial ou razao social.

A busca textual por nome de empresa nao e coberta por APIs publicas gratuitas, entao esta ferramenta retorna um aviso orientando o uso de consultar_cnpj com o CNPJ exato.

Parameters:

Name	Type	Description	Default
nome	str	Nome empresarial ou parte da razao social a procurar.	required
uf	str | None	Sigla do estado para restringir a busca (ex.: "SP", "MG"). Opcional.	None

Returns:

Type	Description
list[dict[str, str]]	list de dicts; atualmente contem um aviso de funcionalidade limitada.

tool_validar_cpf async

tool_validar_cpf(cpf)

Valida o digito verificador de um CPF brasileiro (offline, modulo 11).

Confere apenas a estrutura do numero (11 digitos, nao-repetidos, digitos verificadores). Nao consulta a Receita Federal nem confirma a existencia ou a situacao do titular.

Parameters:

Name	Type	Description	Default
cpf	str	Numero do CPF com 11 digitos, com ou sem formatacao (ex.: "123.456.789-09" ou "12345678909").	required

Returns:

Type	Description
dict[str, Any]	dict indicando se o CPF e matematicamente valido, com versao formatada e motivo da reprovacao.

tool_consultar_nfe async

tool_consultar_nfe(chave_acesso)

Consulta uma NF-e (Nota Fiscal Eletronica) pela chave de acesso de 44 digitos.

Recupera emitente, destinatario, itens, valores e o protocolo de autorizacao da SEFAZ. Use para conferencia, escrituracao fiscal/contabil ou auditoria de notas ja emitidas.

Parameters:

Name	Type	Description	Default
chave_acesso	str	Chave de acesso da NF-e com 44 digitos (aceita com ou sem espacos).	required

Returns:

Type	Description
dict[str, Any]	dict com emitente, destinatario, itens, totais e protocolo da nota.

tool_validar_chave_nfe async

tool_validar_chave_nfe(chave_acesso)

Valida o formato e o digito verificador de uma chave de acesso de NF-e (offline, modulo 11).

Nao consulta a SEFAZ; apenas confere o calculo e decodifica os metadados da chave (UF, ano/mes de emissao, CNPJ emitente, modelo, serie e numero da nota).

Parameters:

Name	Type	Description	Default
chave_acesso	str	Chave de acesso com 44 digitos (aceita com ou sem espacos).	required

Returns:

Type	Description
dict[str, Any]	dict com "valido", "chave_formatada" e, se valida, "uf", "ano_mes_emissao",
dict[str, Any]	"cnpj_emitente", "modelo", "serie" e "numero".

tool_consultar_status_sefaz async

tool_consultar_status_sefaz(uf)

Consulta o status do servico de autorizacao de NF-e da SEFAZ de uma UF.

Indica se o webservice da SEFAZ do estado esta operacional, util para diagnosticar falhas na transmissao de notas fiscais.

Parameters:

Name	Type	Description	Default
uf	str	Sigla do estado com 2 letras (ex.: "SP", "MG", "RJ"). Validada contra as UFs do Brasil.	required

Returns:

Type	Description
dict[str, Any]	dict com o status atual do servico e a descricao correspondente.

tool_parse_nfe_xml async

tool_parse_nfe_xml(xml_content)

Parseia o XML completo de uma NF-e ou NFC-e e retorna os dados estruturados.

Extrai automaticamente a chave de acesso do atributo Id do elemento . Aceita XMLs com ou sem involucro de protocolo , com ou sem namespace do portal fiscal (http://www.portalfiscal.inf.br/nfe).

Parameters:

Name	Type	Description	Default
xml_content	str	XML completo da NF-e ou NFC-e como string. Pode conter o involucro ou ser a NF-e nua. Aceita XML com ou sem namespace do portal fiscal.	required

Returns:

Type	Description
dict[str, Any]	dict com os dados do documento: chave_acesso, modelo, emitente, destinatario,
dict[str, Any]	itens, totais, protocolo_autorizacao e demais campos da NFeResponse.

Raises:

Type	Description
DocumentoParseError	Se o XML for invalido ou a chave nao tiver 44 digitos.
XMLParseError	Se o XML estiver malformado.

tool_gerar_danfe async

tool_gerar_danfe(xml_content)

Gera o DANFE em PDF a partir do XML de uma NF-e (modelo 55).

Utiliza a lib brazilfiscalreport para gerar o DANFE A4 no formato retrato. O PDF e retornado como base64 no campo pdf_base64 do resultado.

NAMESPACE OBRIGATORIO: o XML deve conter o namespace do portal fiscal (http://www.portalfiscal.inf.br/nfe). Modelo 65 (NFC-e) nao e suportado na versao atual.

SEGURANCA: o XML e validado contra XXE (billion-laughs, entidades externas) antes de ser entregue a lib de geracao do PDF.

Parameters:

Name	Type	Description	Default
xml_content	str	XML completo da NF-e como string. Deve conter o namespace do portal fiscal. Aceita XML com ou sem involucro .	required

Returns:

Type	Description
dict[str, Any]	dict com pdf_base64 (PDF em base64), modelo, nome_arquivo, chave_acesso,
dict[str, Any]	numero e serie.

tool_validar_assinatura_nfe async

tool_validar_assinatura_nfe(xml_content, ca_bundle=None)

Valida a assinatura digital XMLDSig de uma NF-e.

Verifica a integridade (DigestValue) e a assinatura criptografica do elemento Signature presente em infNFe. Extrai dados do certificado assinante.

Sem ca_bundle: valida apenas a assinatura criptografica e integridade do digest usando o certificado embutido no proprio XML. Nao verifica se o certificado e confiavel (sem cadeia ICP-Brasil).

Com ca_bundle (PEM): valida a assinatura E a cadeia de confianca ICP-Brasil, garantindo que o certificado foi emitido por uma AC credenciada.

Parameters:

Name	Type	Description	Default
xml_content	str	Conteudo XML da NF-e como string. Validado contra XXE (parse_xml).	required
ca_bundle	str | None	Opcional. Conteudo PEM (nao o caminho, mas o PEM em si) com a cadeia ICP-Brasil para validar o emissor do certificado.	None

Returns:

Type	Description
dict[str, Any]	dict com assinatura_valida (bool), motivo (se invalida), titular (CN),
dict[str, Any]	cnpj_cpf, validade_inicio, validade_fim e ac_emissora.

tool_baixar_nfe_distribuicao async

tool_baixar_nfe_distribuicao(caminho_certificado, senha, cnpj_cpf, uf, modo='distNSU', ultimo_nsu='0', nsu=None, chave=None, ambiente='producao', timeout=30.0)

Baixa documentos fiscais via NFeDistribuicaoDFe com mTLS usando certificado A1 local.

CERTIFICADO LOCAL (opt-in): requer o caminho absoluto para o arquivo .pfx/.p12 e a senha. O certificado NUNCA e enviado a qualquer servidor externo. A autenticacao mTLS e feita diretamente entre o cliente e a SEFAZ.

A Ciencia da Operacao (evento 210200) e pre-requisito para a SEFAZ liberar o XML completo (procNFe) ao destinatario. Sem ela, apenas o resNFe (resumo) fica disponivel. Use manifestar_nfe() apos obter o resNFe.

Parameters:

Name	Type	Description	Default
caminho_certificado	str	Caminho absoluto para o arquivo .pfx ou .p12.	required
senha	str	Senha do certificado. Nunca logada ou incluida em excecoes.	required
cnpj_cpf	str	CNPJ (14 dig) ou CPF (11 dig) do autor da consulta.	required
uf	str	Sigla da UF do autor (ex: "SP") ou codigo IBGE (ex: "35").	required
modo	str	"distNSU" (incremental), "consNSU" (NSU especifico) ou "consChNFe" (por chave de acesso de 44 digitos).	'distNSU'
ultimo_nsu	str	Ultimo NSU recebido para modo distNSU. Default "0" busca todos.	'0'
nsu	str | None	NSU especifico para modo consNSU.	None
chave	str | None	Chave de acesso de 44 digitos para modo consChNFe.	None
ambiente	str	"producao" ou "homologacao".	'producao'
timeout	float	Timeout HTTP em segundos (default 30.0).	30.0

Returns:

Type	Description
dict[str, Any]	dict com ultimo_nsu, max_nsu e documentos (lista com nsu, tipo, schema,
dict[str, Any]	chave e resumo de cada documento retornado).

tool_manifestar_nfe async

tool_manifestar_nfe(chave, tipo_evento, caminho_certificado, senha, cnpj_cpf, uf='91', numero_sequencia=1, justificativa=None, ambiente='producao', timeout=30.0)

Manifesta o destinatario em uma NF-e via NFeRecepcaoEvento.

CERTIFICADO LOCAL (opt-in): requer o caminho absoluto para o arquivo .pfx/.p12 e a senha. O certificado NUNCA e enviado a qualquer servidor. A assinatura XMLDSig do evento e feita localmente e o XML assinado e enviado diretamente a SEFAZ.

Eventos disponiveis: - 210200: Ciencia da Operacao (pre-requisito para obter procNFe) - 210210: Confirmacao da Operacao - 210220: Desconhecimento da Operacao - 210240: Operacao nao Realizada (justificativa OBRIGATORIA, minimo 15 caracteres)

Parameters:

Name	Type	Description	Default
chave	str	Chave de acesso de 44 digitos da NF-e.	required
tipo_evento	str	Codigo do evento ("210200", "210210", "210220" ou "210240").	required
caminho_certificado	str	Caminho absoluto para o arquivo .pfx/.p12.	required
senha	str	Senha do certificado A1. Nunca logada ou incluida em excecoes.	required
cnpj_cpf	str	CNPJ (14 dig) ou CPF (11 dig) do destinatario.	required
uf	str	UF do autor. Default "91" = AN (Ambiente Nacional) para manifestacao.	'91'
numero_sequencia	int	Numero sequencial do evento para esta chave (1 a 20).	1
justificativa	str | None	Obrigatoria para evento 210240 (minimo 15 caracteres).	None
ambiente	str	"producao" ou "homologacao".	'producao'
timeout	float	Timeout HTTP em segundos (default 30.0).	30.0

Returns:

Type	Description
dict[str, Any]	dict com sucesso (bool), chave, tipo_evento, numero_protocolo,
dict[str, Any]	codigo_retorno e motivo retornados pela SEFAZ.

tool_consultar_nfse async

tool_consultar_nfse(numero, municipio, uf, cnpj_prestador=None)

Orienta a consulta de uma NFS-e (Nota Fiscal de Servicos eletronica) por municipio.

A NFS-e e municipal e nao tem padrao nacional unico, entao esta ferramenta retorna o portal da prefeitura, o tipo de sistema (ABRASF, ISS.net etc.) e alternativas de integracao, em vez de buscar os dados da nota diretamente.

Parameters:

Name	Type	Description	Default
numero	str	Numero da NFS-e.	required
municipio	str	Nome do municipio emissor (ex.: "Sao Paulo", "Belo Horizonte").	required
uf	str	Sigla do estado com 2 letras (ex.: "SP", "MG").	required
cnpj_prestador	str | None	CNPJ do prestador de servico. Opcional.	None

Returns:

Type	Description
dict[str, str]	dict com orientacoes de consulta, portal e sistema do municipio e alternativas de automacao.

tool_consultar_simples_nacional async

tool_consultar_simples_nacional(cnpj)

Consulta a situacao de uma empresa no Simples Nacional e no MEI pelo CNPJ.

Retorna se e optante do Simples Nacional e/ou MEI, com datas de opcao e exclusao. Util para definir o regime tributario antes de calcular impostos ou tributar notas fiscais.

Parameters:

Name	Type	Description	Default
cnpj	str	Numero do CNPJ com 14 digitos, com ou sem formatacao.	required

Returns:

Type	Description
dict[str, Any]	dict com a situacao no Simples Nacional e no MEI e respectivas datas.

tool_analisar_sped async

tool_analisar_sped(conteudo, nome_arquivo=None)

Analisa um arquivo SPED e extrai periodo, empresa, contagem de registros e erros.

Identifica o tipo de escrituracao pelo registro 0000 (EFD-ICMS/IPI, EFD-Contribuicoes, ECD, ECF) e devolve um resumo estruturado, com avisos e erros de integridade basica.

Parameters:

Name	Type	Description	Default
conteudo	str	Texto do arquivo SPED (layout delimitado por pipe "|"), nao um caminho.	required
nome_arquivo	str | None	Nome do arquivo, apenas informativo. Opcional.	None

Returns:

Type	Description
dict[str, Any]	dict com tipo de SPED, dados de abertura, periodo, contagem de registros, avisos e erros.

tool_listar_registros_sped async

tool_listar_registros_sped(conteudo, tipo_registro)

Lista todas as ocorrencias de um tipo de registro dentro de um arquivo SPED.

Para cada linha cujo codigo inicial coincide com tipo_registro, retorna o codigo, os campos concatenados por pipe e a linha bruta.

Parameters:

Name	Type	Description	Default
conteudo	str	Texto do arquivo SPED (layout delimitado por pipe "|").	required
tipo_registro	str	Codigo do registro a buscar (ex.: "C100", "E110", "0150"). Case-insensitive.	required

Returns:

Type	Description
list[dict[str, str | list[str]]]	list de dicts com "registro", "campos" e "raw" para cada ocorrencia encontrada.

tool_listar_eventos_esocial async

tool_listar_eventos_esocial(grupo=None)

Lista os eventos do eSocial (layouts da serie S-) do catalogo interno.

Retorna codigo, nome, grupo e descricao de cada evento, opcionalmente filtrados por grupo.

Parameters:

Name	Type	Description	Default
grupo	str | None	Filtro por grupo, com correspondencia parcial e sem distincao de maiusculas (ex.: "Tabelas", "Nao Periodicos", "Periodicos", "Exclusao", "Totalizadores"). Se None, retorna todos os eventos ordenados por codigo.	None

Returns:

Type	Description
list[dict[str, Any]]	list de dicts com codigo, nome, grupo e descricao de cada evento.

tool_validar_evento_esocial async

tool_validar_evento_esocial(xml_conteudo)

Valida a estrutura basica de um XML de evento do eSocial.

Verifica o elemento raiz, identifica o codigo do evento (elemento "evt...") e extrai a versao do leiaute. Nao substitui a validacao contra o schema XSD oficial.

Parameters:

Name	Type	Description	Default
xml_conteudo	str	Conteudo (texto) do XML do evento eSocial.	required

Returns:

Type	Description
dict[str, Any]	dict com o evento detectado, a versao, o resultado da validacao e listas de erros e avisos.

tool_consultar_certidao_federal async

tool_consultar_certidao_federal(cnpj_cpf)

Orienta a obtencao da Certidao Negativa de Debitos federais (CND da RFB/PGFN) por CPF ou CNPJ.

Detecta o tipo de documento, valida o numero e retorna as URLs oficiais de emissao e verificacao, o acesso ao e-CAC e alternativas de automacao. Nao emite a certidao (nao ha API publica).

Parameters:

Name	Type	Description	Default
cnpj_cpf	str	CPF (11 digitos) ou CNPJ (14 digitos), com ou sem formatacao.	required

Returns:

Type	Description
dict[str, str]	dict com tipo de documento, motivo da consulta manual, URLs de emissao/verificacao e alternativas.

tool_consultar_certidao_fgts async

tool_consultar_certidao_fgts(cnpj)

Orienta a obtencao do Certificado de Regularidade do FGTS (CRF) por CNPJ.

Valida o CNPJ e retorna a URL de consulta no portal da Caixa, o Conectividade Social e orientacoes de automacao. Nao emite o certificado (nao ha API publica aberta).

Parameters:

Name	Type	Description	Default
cnpj	str	CNPJ do empregador com 14 digitos, com ou sem formatacao.	required

Returns:

Type	Description
dict[str, str]	dict com orgao, motivo da consulta manual, URLs de consulta e orientacoes de automacao.

tool_analyze_cnpj_compliance async

tool_analyze_cnpj_compliance(cnpj)

Analise consolidada de compliance fiscal de um CNPJ.

Combina dados da Receita Federal, Simples Nacional e CNAE para produzir um relatorio com score 0-100, classificacao de risco e achados acionaveis.

Parameters:

Name	Type	Description	Default
cnpj	str	Numero do CNPJ com 14 digitos, com ou sem formatacao.	required

Returns:

Type	Description
dict[str, Any]	dict com score, risco, situacao, regime, cnae e lista de achados.

tool_compare_tax_regimes async

tool_compare_tax_regimes(faturamento_anual, setor, folha_pagamento_anual=None)

Compara regimes tributarios para um cenário.

tool_simular_transicao_reforma_tributaria async

tool_simular_transicao_reforma_tributaria(faturamento_anual, setor, regime_atual, aliquota_icms_atual=None, aliquota_iss_atual=None, aliquota_pis_cofins=None)

Simula o impacto financeiro da transicao para o novo sistema tributario (LC 214/2025).

Projeta, ano a ano de 2026 a 2033, a carga tributaria estimada do regime antigo (PIS/COFINS + ICMS ou ISS) e do regime novo (CBS + IBS), conforme o cronograma de transicao da LC 214/2025: teste em 2026, CBS plena em 2027-2028, reducao gradual de ICMS/ISS de 2029 a 2032 e extincao total em 2033.

Parameters:

Name	Type	Description	Default
faturamento_anual	float	Receita bruta anual em reais. Deve ser positivo.	required
setor	str	Setor da empresa. Aceita: "comércio", "serviços" ou "indústria".	required
regime_atual	str	Regime tributario atual. Aceita: "Simples Nacional", "Lucro Presumido" ou "Lucro Real".	required
aliquota_icms_atual	float | None	Aliquota do ICMS (%) vigente no estado da empresa. Obrigatoria para comercio/industria para maior precisao. Se None, assume 12%.	None
aliquota_iss_atual	float | None	Aliquota do ISS (%) vigente no municipio da empresa. Obrigatoria para servicos para maior precisao. Se None, assume 5%.	None
aliquota_pis_cofins	float | None	Aliquota efetiva de PIS/COFINS (%) sobre o faturamento. Se None, usa o padrao do regime informado (LP: 3,65%; LR: 9,25%; SN: 3,65%).	None

Returns:

Type	Description
dict[str, Any]	dict com projecao anual 2026-2033, premissas utilizadas e avisos legais obrigatorios.

tool_risk_score_supplier async

tool_risk_score_supplier(cnpj, criterios_estritos=False)

Calcula score de risco para due diligence de fornecedor.

Agrega o ComplianceReport do CNPJ com pesos conservadores de contratacao. Com criterios_estritos=True, aplica reducao adicional de 10 pontos para politicas anti-corrupcao (ex: Lei 12.846/2013).

Parameters:

Name	Type	Description	Default
cnpj	str	Numero do CNPJ com 14 digitos, com ou sem formatacao.	required
criterios_estritos	bool	Se True, aplica pesos mais rigorosos. Padrao: False.	False

Returns:

Type	Description
dict[str, Any]	dict com score, recomendacao e justificativa da classificacao.

tool_consultar_empresas_lote async

tool_consultar_empresas_lote(cnpjs, criterios_estritos=False)

Consulta em lote consolidada de compliance e risco para ate 50 CNPJs.

Para cada CNPJ valido, executa analyze_cnpj_compliance + risk_score_supplier em paralelo. CNPJs com falha retornam erro individual sem abortar o lote.

Parameters:

Name	Type	Description	Default
cnpjs	list[str]	Lista de CNPJs (max 50), com ou sem formatacao.	required
criterios_estritos	bool	Se True, usa pesos rigorosos no score de risco.	False

Returns:

Type	Description
dict[str, Any]	dict com resultados por CNPJ e lista de erros individuais.

tool_validate_nfe_full async

tool_validate_nfe_full(xml_path)

Validacao consolidada de NFe.

tool_summarize_sped async

tool_summarize_sped(file_path)

Sumarizacao executiva de arquivo SPED.

main

main()

Inicia o servidor MCP.

Modo de transporte configurável via argumento --transport ou variável de ambiente FASTMCP_TRANSPORT. Valores aceitos: stdio (padrão), sse, http, streamable-http.

Para HTTP/SSE, a porta é configurada via variável PORT (padrão: 8000).