Nota Fiscal Mcp

io.github.FAVIOSENGERPublished by GitHub account FAVIOSENGERv0.1.2Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Local MCP server that lets an AI assistant issue, check and cancel Brazilian NF-e and NFS-e invoices through the Focus NFe provider.

What you can do
  • Issue service invoices (NFS-e) and product invoices (NF-e, model 55) with fiscal content assembled by the assistant
  • Check status and retrieve XML/PDF links for issued NFS-e and NF-e
  • Cancel authorized NFS-e and NF-e, with NF-e cancellation limited to 24 hours after issuance
  • Run the same six tools in a mock mode that fakes provider responses for testing
When to use it
Useful for Brazilian freelancers and companies that already bill through Focus NFe and want to draft, issue, look up or cancel service and product invoices from a chat client instead of a fiscal web system.
Requirements
Runs locally via npx (Node.js) as a stdio process in a desktop MCP client such as Claude Desktop, Claude Code or Cursor. Needs a Focus NFe account and its token in FOCUS_NFE_TOKEN; FOCUS_NFE_AMBIENTE selects homologacao (default) or producao. A mock provider mode works without a token. Network access to the provider is required.
Before you install
Issuing and cancelling invoices are real fiscal actions: in producao they create legally valid documents, and NF-e cancellation is only possible within 24 hours. The Focus NFe token is a secret passed via FOCUS_NFE_TOKEN and should not be committed to code or repositories. Start in homologacao, which does not issue invoices with fiscal value, and confirm municipal payload fields before switching to production.

Installation

In SourceWeft

  1. Open Nota Fiscal Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

🧾 nota-fiscal-mcp

[npm version] [License: MIT] [MCP Registry]

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 ACMEClaude: ✅ 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:

json
{  "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:

json
"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

bash
git clone https://github.com/FAVIOSENGER/nota-fiscal-mcp.gitcd nota-fiscal-mcpnpm installnpm run buildPROVIDER=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

Source: README.md at commit e66f27e

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.2LatestOct 13, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts