English Français العربية

io.github.FAVIOSENGER/nota-fiscal-mcp

السجل الرسمي الذكاء الاصطناعي والوكلاء

Emissao, consulta e cancelamento de NF-e e NFS-e no Brasil para agentes de IA, via Focus NFe.

الشيفرة المصدرية التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package nota-fiscal-mcp
Claude Code 
claude mcp add nota-fiscal-mcp -e 'FOCUS_NFE_TOKEN=<your focus_nfe_token>' -e 'FOCUS_NFE_AMBIENTE=<FOCUS_NFE_AMBIENTE>' -- npx -y nota-fiscal-mcp@0.1.2
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "nota-fiscal-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "nota-fiscal-mcp@0.1.2"
            ],
            "env": {
                "FOCUS_NFE_TOKEN": "<your focus_nfe_token>",
                "FOCUS_NFE_AMBIENTE": "<FOCUS_NFE_AMBIENTE>"
            }
        }
    }
}

متغيرات البيئة

  • FOCUS_NFE_TOKEN إلزامي سري Token da conta Focus NFe (homologacao ou producao).
  • FOCUS_NFE_AMBIENTE Ambiente: 'homologacao' (padrao) ou 'producao'.

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. 🧾 nota-fiscal-mcp
  2. ✨ O que ele faz
  3. 🚀 Instalação
  4. 🔑 Pré-requisito: uma conta de provedor fiscal
  5. ⚙️ Variáveis de ambiente
  6. 🧪 Modo simulação (sem provedor)
  7. 🔒 Segurança
  8. 🛠️ Desenvolvimento
  9. 📍 Status
  10. 📄 Licença

🧾 nota-fiscal-mcp

Deixe a IA emitir suas notas fiscais.

nota-fiscal-mcp é um servidor MCP que dá a qualquer agente de IA — Claude Desktop, Claude Code, Cursor e outros — o poder de emitir, consultar e cancelar NF-e e NFS-e no Brasil. Ele conversa com um provedor fiscal (Focus NFe) que já resolve a parte difícil: certificado digital, comunicação com a SEFAZ e com as prefeituras.

Você conversa. A IA emite.

Você:   emita uma NFS-e de R$ 500 de consultoria em TI para o cliente ACME
Claude: ✅ NFS-e emitida — nota nº 3070, autorizada. Aqui está o PDF e o XML.

Sem abrir sistema, sem preencher formulário, sem decorar campo de ISS.

✨ O que ele faz

FerramentaO que faz
emitir_nfseEmite uma Nota Fiscal de Serviço (NFS-e)
consultar_nfseConsulta o status e os links (XML/PDF) de uma NFS-e
cancelar_nfseCancela uma NFS-e autorizada
emitir_nfeEmite uma Nota Fiscal de produto (NF-e, modelo 55)
consultar_nfeConsulta status e downloads de uma NF-e
cancelar_nfeCancela uma NF-e (até 24h após a emissão)

A IA monta o conteúdo fiscal da nota; o servidor cuida de autenticação, referência e comunicação com o provedor.

🚀 Instalação

Não precisa clonar nem compilar nada — o pacote roda direto via npx.

Claude Desktop

Abra o arquivo de configuração (claude_desktop_config.json) e adicione:

{
  "mcpServers": {
    "nota-fiscal": {
      "command": "npx",
      "args": ["-y", "nota-fiscal-mcp"],
      "env": {
        "FOCUS_NFE_TOKEN": "seu_token_aqui",
        "FOCUS_NFE_AMBIENTE": "homologacao"
      }
    }
  }
}

Reinicie o Claude Desktop. Pronto — as 6 ferramentas aparecem para o agente.

Funciona do mesmo jeito em qualquer cliente MCP (Claude Code, Cursor, etc.): é só apontar o comando npx -y nota-fiscal-mcp com as variáveis de ambiente.

🔑 Pré-requisito: uma conta de provedor fiscal

Para emitir de verdade você precisa de um token de um provedor fiscal. Hoje o nota-fiscal-mcp usa a Focus NFe, que oferece ambiente de testes (homologação) e cuida de certificado + SEFAZ por você.

  1. Crie sua conta na Focus NFe
  2. Cadastre sua empresa e pegue o token de homologação (em Painel API → Tokens).
  3. Coloque o token na configuração acima e teste à vontade — homologação não emite nota com valor fiscal.
  4. Quando tudo estiver certo, troque FOCUS_NFE_AMBIENTE para producao e use o token de produção.

⚙️ Variáveis de ambiente

VariávelObrigatóriaDescrição
FOCUS_NFE_TOKENsimToken da sua conta Focus NFe
FOCUS_NFE_AMBIENTEnãohomologacao (padrão) ou producao

🧪 Modo simulação (sem provedor)

Quer testar o fluxo sem token nenhum? Rode em modo simulação — ele finge as respostas e deixa você exercitar as 6 ferramentas de ponta a ponta:

"env": { "PROVIDER": "mock" }

🔒 Segurança

  • Seu token vai nas variáveis de ambiente — nunca o coloque dentro do código nem suba num repositório.
  • Comece sempre em homologação. Só vá para produção depois de validar.
  • O projeto é open-source: você roda com a sua conta e o seu token. Nada passa por servidores de terceiros.

🛠️ Desenvolvimento

git clone https://github.com/FAVIOSENGER/nota-fiscal-mcp.git
cd nota-fiscal-mcp
npm install
npm run build
PROVIDER=mock node test/client.mjs   # testa as 6 ferramentas em simulação

📍 Status

v0.1.2 — primeira geração pública. Suporte a NF-e e NFS-e via Focus NFe. Os campos do payload seguem o padrão da documentação da Focus NFe; confirme os dados do seu município antes de produção.

📖 Artigo / tutorial: Como fazer a IA emitir sua nota fiscal (NF-e e NFS-e) usando MCP

Ideias, bugs e sugestões: abra uma issue.

📄 Licença

MIT © Favio Senger

الأسئلة الشائعة

ما هو io.github.FAVIOSENGER/nota-fiscal-mcp؟

Emissao, consulta e cancelamento de NF-e e NFS-e no Brasil para agentes de IA, via Focus NFe.

كيف أثبّت io.github.FAVIOSENGER/nota-fiscal-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add nota-fiscal-mcp -e 'FOCUS_NFE_TOKEN=<your focus_nfe_token>' -e 'FOCUS_NFE_AMBIENTE=<FOCUS_NFE_AMBIENTE>' -- npx -y nota-fiscal-mcp@0.1.2. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.FAVIOSENGER/nota-fiscal-mcp إلى مفتاح API؟

نعم. يتطلب FOCUS_NFE_TOKEN، وتضبطها في إعداداته.

هل io.github.FAVIOSENGER/nota-fiscal-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.FAVIOSENGER/nota-fiscal-mcp؟

ينشره FAVIOSENGER. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.