nfse-sdk
SDK TypeScript para emitir, consultar e gerenciar NFS-e Nacional.
Install / Use
claude mcp add useinvio -- npx -y github:useinvio/nfse-sdkIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Development & EngineeringSupported Platforms
Tags
Our assessment of nfse-sdk
nfse-sdk scores 71/100 on our quality scale, 3864th of 4,704 Development & Engineering skills we index.
Its MCP Server is 6.1 KB long, well organised into 9 sections with 6 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 4 days ago, so nfse-sdk is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 87/100, with 2 cautions from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
nfse-sdk compared with similar skills
All 4 of these similar skills score higher than nfse-sdk; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| nfse-sdk (this skill)by useinvio | 71 | 3 | 4d ago | MCP Server |
| taste-skillby Leonxlnx | 100 | 117.0k | 8d ago | CLAUDE.md |
| Agent-Reachby Panniantong | 100 | 112.4k | 9d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.9k | today | CLAUDE.md |
Frequently asked questions
- How do I install nfse-sdk?
- Run
claude mcp add useinvio -- npx -y github:useinvio/nfse-sdk. The install tabs above show the steps for each supported agent. - Which AI agents does nfse-sdk work with?
- It is written for Claude Code and Claude Desktop, as a MCP Server file. Other agents that read the same format can often use it too.
- Is nfse-sdk safe to use?
- It is MIT-licensed and scores 87/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is nfse-sdk still maintained?
- The repository was last updated 4 days ago, so nfse-sdk is actively maintained.
Skill content
View source on GitHub@useinvio/nfse-sdk
Website · Playground · Documentação · English
<img width="959" height="296" alt="NFS-e SDK" src="https://github.com/user-attachments/assets/d6c45737-e7ca-4ea7-a06f-d93b7c16e4f0" />Emita, consulte e cancele NFS-e Nacional em TypeScript, sem escrever XML fiscal na mão.
Você descreve a nota em JSON; o SDK monta a DPS, valida contra o XSD oficial,
assina com o certificado A1, compacta, envia por mTLS para a SEFIN e devolve a
resposta oficial em formato estruturado. Sem binários nativos e sem xmllint.
O que ele faz
| Operação | Função | No NfseClient |
|---|---|---|
| Emitir a partir de JSON ou XML | emitirNfse | invoices.create |
| Validar sem enviar (JSON + XSD) | validateDpsJsonRequest, buildDpsFromJson | invoices.buildDpsJson |
| Consultar com resultado tipado | obterNfse | invoices.retrieve |
| Recuperar uma emissão após timeout | recuperarNfsePorDps | invoices.recover |
| Cancelar / cancelar por substituição | cancelarNfse, cancelarNfsePorSubstituicao | invoices.cancel, invoices.cancelBySubstitution |
| Baixar o DANFSe em PDF | baixarDanfse | invoices.danfse |
| Distribuição por NSU e parâmetros municipais (ADN) | distribuirDfePorNsu, consultarAliquota… | distribution, municipalParameters |
| Explicar rejeições com o texto oficial | explicarRejeicao, explicarErros, uma página por código | – |
| Usar pelo terminal | npx nfse init, doctor, validate, emit, explain | – |
| Testar sem certificado nem rede | @useinvio/nfse-sdk/testing | – |
| Servidor MCP e ferramentas para agentes de IA | npx -y @useinvio/nfse-mcp, @useinvio/nfse-sdk/agent | – |
Instalação
npm install @useinvio/nfse-sdk
Node.js 20 ou mais recente. Nada para instalar no sistema: a validação XSD roda em WebAssembly.
Em 60 segundos
NFSE_CERT_PATH=./certificado.pfx
NFSE_CERT_PASSWORD=sua-senha
import { emitirNfse, EmitirNotaError, NfseCertificate } from '@useinvio/nfse-sdk';
const certificado = NfseCertificate.fromEnv(); // a chave privada nunca aparece em logs
const nota = {
ambiente: 'restrita' as const, // produção restrita: o sandbox oficial
prestador: {
cnpj: '12345678000195',
cLocEmi: '4106902',
serie: '1601',
opSimpNac: '1',
regEspTrib: '0',
},
servico: {
cTribNac: '010201',
xDescServ: 'Desenvolvimento de software',
cLocPrestacao: '4106902',
cNBS: '115022000',
},
emissao: {
nDPS: '1',
dhEmi: '2026-06-15T10:30:00-03:00',
dCompet: '2026-06-01',
valores: { vServ: '1500.00' },
tributacaoMunicipal: { tribISSQN: '1', tpRetISSQN: '1' },
tributacaoFederal: { piscofins: { CST: '07' } },
totTrib: { pTotTribFed: '0.00', pTotTribEst: '0.00', pTotTribMun: '5.00' },
},
};
try {
const { chaveAcesso, nfseXml } = await emitirNfse(nota, certificado);
console.log(chaveAcesso); // chave de 50 dígitos
} catch (error) {
if (!(error instanceof EmitirNotaError)) throw error;
for (const rejeicao of error.erros) console.error(rejeicao.Codigo, rejeicao.Descricao);
}
Primeira vez? Siga o tutorial: emitir, consultar, baixar o PDF e cancelar na produção restrita, do zero. Ou experimente sem certificado, pelo terminal:
npx nfse init && npx nfse emit nota.json --mock
Documentação
| Guia | |
|---|---|
| Certificado A1 | Variáveis de ambiente, cofres de segredo, vários emitentes. |
| Emitir | JSON, NfseClient, XML pronto, série e número. |
| Consultar e DANFSe | Resultado tipado e PDF. |
| Recuperar após timeout | Sem notas duplicadas quando a conexão cai. |
| Cancelar | e101101 e substituição (e105102). |
| Erros e rejeições | O que cada erro significa e o que fazer. |
| Linha de comando | nfse doctor, emit, cancel, explain. |
| Testar sem certificado | SEFIN simulada para o seu CI. |
| Agentes de IA e MCP | Servidor MCP, plugin do Claude Code, ferramentas para o seu agente. |
| Referência da API | Todas as funções. |
| Mapeamento do JSON | Cada campo de DpsJsonRequest. |
Exemplos executáveis em examples/.
Com agentes de IA
Emita uma NFS-e conversando com o Claude. Para experimentar sem certificado, o modo de teste usa uma SEFIN simulada:
claude mcp add nfse --env NFSE_MCP_MOCK=1 --env NFSE_MCP_ALLOW_WRITE=1 -- npx -y @useinvio/nfse-mcp
Ou instale o plugin do Claude Code, que inclui o servidor e uma skill com o fluxo:
/plugin install nfse-nacional --marketplace useinvio/nfse-sdk
Emitir e cancelar sempre passam por um resumo que você aprova antes do envio, e
o certificado nunca chega ao modelo. Veja o guia de agentes e MCP.
Para assistentes de código, o pacote inclui llms.txt.
O que fica com a sua aplicação
O SDK cuida do protocolo; ele não é um motor fiscal. Códigos de serviço, CST, alíquotas, retenções, regime tributário e a numeração da DPS são decisões da sua aplicação e de quem cuida da parte tributária. Campos fiscais obrigatórios nunca recebem valores padrão silenciosos. O grupo IBS/CBS da reforma tributária ainda não é suportado.
Contribuir
Issues e PRs são bem-vindos. Veja CONTRIBUTING.md e o CHANGELOG.
Licença
MIT © Invio
Related Skills
taste-skill
117.0kAgent skills that give coding agents taste: art direction, reference images and a browser check instead of generic AI pages
Agent-Reach
112.4kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.9kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
