io.github.FAVIOSENGER/nota-fiscal-mcp

🧾 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

Ferramenta	O que faz
emitir_nfse	Emite uma Nota Fiscal de Serviço (NFS-e)
consultar_nfse	Consulta o status e os links (XML/PDF) de uma NFS-e
cancelar_nfse	Cancela uma NFS-e autorizada
emitir_nfe	Emite uma Nota Fiscal de produto (NF-e, modelo 55)
consultar_nfe	Consulta status e downloads de uma NF-e
cancelar_nfe	Cancela 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ável	Obrigatória	Descrição
FOCUS_NFE_TOKEN	sim	Token da sua conta Focus NFe
FOCUS_NFE_AMBIENTE	não	homologacao (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