MCP NFS-e (ISSWeb / Fiorilli)

Servidor MCP (Model Context Protocol) para buscar, baixar, consultar e (em breve) emitir Notas Fiscais de Serviço eletrônicas (NFS-e) em prefeituras que usam o sistema ISSWeb da Fiorilli — padrão nacional (com IBS/CBS).

Multiempresa: cada empresa/escritório configura o próprio login e senha e passa a buscar e baixar suas notas de forma segura e prática. Feito para escritórios de contabilidade gerenciarem vários clientes. Pode ser acionado por IA (Claude) ou por scripts. Padrão: Ariquemes/RO — adaptável a outras cidades que usem o mesmo sistema.

Estado atual

🔒 Segurança: tudo é somente leitura. A emissão está sendo construída em modo preview (preenche os campos mas não salva no portal); o salvar real exigirá dupla trava (NFSE_PERMITIR_EMISSAO=true + confirmar: true).

Related MCP server: Prefeitura MT Cuiabá: NFS-e

Como funciona

• Portal (Playwright): faz login com usuário/senha e usa a tela de pesquisa para listar as notas de um período e baixar o XML de cada uma e a DANFSe (PDF).

• WebService Nacional: consulta aberta (sem login) pela chave de acesso — devolve o XML completo no layout nacional.

Instalação

npm install
npx playwright install chromium

Configuração

1 empresa — .env

Copie .env.example para .env:

NFSE_USUARIO=seu_usuario_do_portal
NFSE_SENHA=sua_senha_do_portal
NFSE_CNPJ=00000000000000
NFSE_INSCRICAO_MUNICIPAL=

Vários clientes — clientes.json (contabilidade)

Copie clientes.example.json para clientes.json (fica fora do Git):

{
  "cliente_a": { "nome": "Empresa A",  "usuario": "...", "senha": "...", "cnpj": "...", "im": "..." },
  "cliente_b": { "nome": "Empresa B",  "usuario": "...", "senha": "...", "cnpj": "...", "im": "..." }
}

Depois é só passar empresa: "cliente_a" nas ferramentas.

Ferramentas MCP

Todas as ferramentas de portal aceitam empresa (multi-cliente, opcional).

Teste rápido (sem MCP)

# Listar notas de um período (precisa de login/senha no .env):
node scripts/pesquisar-teste.js 01/08/2026 31/08/2026

# Baixar XML + DANFSe de uma nota:
node scripts/baixar-teste.js 5 2026-08-01 2026-08-31

# Consultar pela chave (WebService, sem login):
node scripts/testar-conexao.js 11000231268076089000103000000000000526085425791624

Uso como MCP

Claude Desktop — claude_desktop_config.json

{
  "mcpServers": {
    "nfse": {
      "command": "node",
      "args": ["CAMINHO_DO_PROJETO/src/index.js"],
      "env": { "NFSE_USUARIO": "usuario", "NFSE_SENHA": "senha" }
    }
  }
}

Claude Code (CLI)

claude mcp add nfse --env NFSE_USUARIO=usuario --env NFSE_SENHA=senha -- node "CAMINHO_DO_PROJETO\src\index.js"

Segurança

• Credenciais ficam no .env/clientes.json de cada instalação — nunca vão para o Git.

• Tudo é read-only; a emissão fica travada (preview) até liberação explícita.

• Ferramenta não oficial, sem vínculo com a Prefeitura ou com a Fiorilli.

Estrutura

src/
  index.js            servidor MCP (10 ferramentas)
  config.js           configuração multiempresa
  clientes.js         gestão multi-cliente (clientes.json)
  cnpj.js             busca de empresa por CNPJ
  soap-client.js      cliente SOAP + parser
  nacional.js         envelopes do WebService Nacional
  parse-nfse.js       XML nacional -> JSON limpo
  consultar.js        camada de consulta (WebService)
  portal/
    login.js          login no portal (Playwright)
    pesquisar.js      lista notas por período
    baixar.js         baixa XML + DANFSe (nota ou período)
scripts/
  pesquisar-teste.js  testa a listagem
  baixar-teste.js     testa o download de uma nota
  testar-conexao.js   testa a consulta (WebService)
  testar-mcp.js       smoke test do protocolo MCP
  inspecionar-portal.js  mapeia campos de uma tela do portal

Roadmap

1. Emissão (preview → real): preencher a tela de emissão (tomador por CNPJ, serviço, valores) e salvar só com a dupla trava de segurança.

2. Paginação no download em lote (períodos com muitas notas).

3. Multicidade: catálogo de prefeituras ISSWeb/Fiorilli.