Brazil Invoices (NFS-e nota fiscal de serviço)

Official3 toolsLive

by junter1989k-ai · JavaScript

Brazil NFS-e service invoices for AI agents via Focus NFe and NFe.io. Stateless, never stores data.

Topics

ai-agentsbrazile-invoiceinvoicingmcpmcp-servernfsenota-fiscalai-agentclaudeinvoicenfetaxwishpool

Captured live from the server via tools/list.

create_invoice

Issue a Brazil NFS-e (nota fiscal de serviço eletrônica — the electronic service invoice municipalities/prefeituras require). Two interchangeable providers behind one tool (bring your own credentials as HTTP headers; this server stores nothing, and the merchant certificate + municipal registration stay in the merchant's own provider account): (A) FOCUS NFe — header x-focusnfe-token (free homologação/sandbox token issues test NFS-e with no fiscal effect; the produção token issues real ones; add x-focusnfe-mode: production to switch, default is the safer sandbox). (B) NFE.IO — headers x-nfeio-key (your NFe.io API key) + x-nfeio-company-id (the id of your issuing company/empresa in NFe.io, which holds the CNPJ, municipal registration and certificate; whether it is a Test or Production company — and thus fiscal effect — is set in your NFe.io account, not per request). Routing: whichever credential headers you send picks the provider; if both are present Focus NFe wins unless you set header x-invoice-provider: nfeio. ISSUANCE IS ASYNCHRONOUS: this returns status PROCESSING plus a ref — poll query_invoice with that ref until AUTHORIZED (nota autorizada) or ERROR. Ref semantics differ: with Focus NFe the ref is yours (auto-generated if omitted); with NFe.io the ref returned is NFe.io's own invoice id (a passed-in ref is ignored). For NFe.io the issuer comes from x-nfeio-company-id, so the prestador_* fields are validated but not forwarded. This is for service invoices (serviços); NF-e for physical goods is on the v2 roadmap.

Parameters17

prestador_cnpj	string	required	Service provider (merchant) CNPJ, 14 digits — the business issuing the invoice. Must match the certificate configured in the Focus NFe account.
prestador_inscricao_municipal	string	required	Provider municipal registration (inscrição municipal) issued by the prefeitura where the service is taxed.
prestador_codigo_municipio	string	optional	IBGE 7-digit code of the provider municipality (código do município), e.g. 3550308 for São Paulo. Also used as the service municipality unless the service is elsewhere.
customer_name	string	required	Buyer/taker legal or full name (razão social or nome do tomador).
customer_tax_id	string	required	Buyer CPF (11 digits, individual) or CNPJ (14 digits, company). Digits only or formatted — punctuation is stripped.
customer_email	string	optional	Optional buyer email — Focus NFe can email the NFS-e to it once authorized.
valor_servicos	number	required	Total service amount in BRL (reais). This is the invoice total the ISS tax and owner policy caps apply to.
discriminacao	string	required	Description of the service rendered (discriminação do serviço) — free text shown on the NFS-e.
item_lista_servico	string	required	Service list item code from Lei Complementar 116 (lista de serviços), e.g. "01.07" software support, "17.09" consultoria. Determines the ISS classification; required by every prefeitura.
aliquota	number	optional	ISS rate. Focus NFe expects it as a decimal fraction (0.05 = 5%). Optional — many municipalities derive it from item_lista_servico; pass it only if your prefeitura requires it.
iss_retido	boolean	optional	Whether ISS is withheld by the buyer (ISS retido na fonte). Default false.
codigo_tributario_municipio	string	optional	Optional municipal tax/service code (código tributário do município / CNAE-based) some prefeituras require in addition to item_lista_servico.
data_emissao	string	optional	Optional issue date-time in ISO-8601 with offset, e.g. 2026-07-10T10:30:00-03:00. Defaults to now.
natureza_operacao	string	optional	Operation nature code (natureza da operação). Default "1" (tributação no município).
optante_simples_nacional	boolean	optional	Whether the provider is a Simples Nacional opter. Default true.
ref	string	optional	Optional caller-chosen unique reference for this NFS-e (used to poll/cancel). Applies to Focus NFe only (auto-generated if omitted); NFe.io ignores it and returns its own invoice id as the ref.
provider	string	optional	Optional explicit provider. Omit to auto-route by which credential headers you sent (x-focusnfe-token -> focusnfe, x-nfeio-key -> nfeio). Overrides header x-invoice-provider.

Raw schema

{
  "type": "object",
  "properties": {
    "prestador_cnpj": {
      "type": "string",
      "description": "Service provider (merchant) CNPJ, 14 digits — the business issuing the invoice. Must match the certificate configured in the Focus NFe account."
    },
    "prestador_inscricao_municipal": {
      "type": "string",
      "description": "Provider municipal registration (inscrição municipal) issued by the prefeitura where the service is taxed."
    },
    "prestador_codigo_municipio": {
      "type": "string",
      "description": "IBGE 7-digit code of the provider municipality (código do município), e.g. 3550308 for São Paulo. Also used as the service municipality unless the service is elsewhere."
    },
    "customer_name": {
      "type": "string",
      "description": "Buyer/taker legal or full name (razão social or nome do tomador)."
    },
    "customer_tax_id": {
      "type": "string",
      "description": "Buyer CPF (11 digits, individual) or CNPJ (14 digits, company). Digits only or formatted — punctuation is stripped."
    },
    "customer_email": {
      "type": "string",
      "description": "Optional buyer email — Focus NFe can email the NFS-e to it once authorized."
    },
    "valor_servicos": {
      "type": "number",
      "description": "Total service amount in BRL (reais). This is the invoice total the ISS tax and owner policy caps apply to."
    },
    "discriminacao": {
      "type": "string",
      "description": "Description of the service rendered (discriminação do serviço) — free text shown on the NFS-e."
    },
    "item_lista_servico": {
      "type": "string",
      "description": "Service list item code from Lei Complementar 116 (lista de serviços), e.g. \"01.07\" software support, \"17.09\" consultoria. Determines the ISS classification; required by every prefeitura."
    },
    "aliquota": {
      "type": "number",
      "description": "ISS rate. Focus NFe expects it as a decimal fraction (0.05 = 5%). Optional — many municipalities derive it from item_lista_servico; pass it only if your prefeitura requires it."
    },
    "iss_retido": {
      "type": "boolean",
      "description": "Whether ISS is withheld by the buyer (ISS retido na fonte). Default false."
    },
    "codigo_tributario_municipio": {
      "type": "string",
      "description": "Optional municipal tax/service code (código tributário do município / CNAE-based) some prefeituras require in addition to item_lista_servico."
    },
    "data_emissao": {
      "type": "string",
      "description": "Optional issue date-time in ISO-8601 with offset, e.g. 2026-07-10T10:30:00-03:00. Defaults to now."
    },
    "natureza_operacao": {
      "type": "string",
      "description": "Operation nature code (natureza da operação). Default \"1\" (tributação no município)."
    },
    "optante_simples_nacional": {
      "type": "boolean",
      "description": "Whether the provider is a Simples Nacional opter. Default true."
    },
    "ref": {
      "type": "string",
      "description": "Optional caller-chosen unique reference for this NFS-e (used to poll/cancel). Applies to Focus NFe only (auto-generated if omitted); NFe.io ignores it and returns its own invoice id as the ref."
    },
    "provider": {
      "type": "string",
      "enum": [
        "focusnfe",
        "nfeio"
      ],
      "description": "Optional explicit provider. Omit to auto-route by which credential headers you sent (x-focusnfe-token -> focusnfe, x-nfeio-key -> nfeio). Overrides header x-invoice-provider."
    }
  },
  "required": [
    "prestador_cnpj",
    "prestador_inscricao_municipal",
    "customer_name",
    "customer_tax_id",
    "valor_servicos",
    "discriminacao",
    "item_lista_servico"
  ]
}

query_invoice

Check a Brazil NFS-e created by create_invoice, using its ref. Status values: PROCESSING (prefeitura is still authorizing — poll again shortly), AUTHORIZED (nota autorizada — numero and codigo_verificacao are populated, url links the official NFS-e), ERROR (authorization was rejected — see message for the reason), CANCELED (voided). Safe to call anytime.

Parameters2

ref	string	required	The ref returned by create_invoice (your ref for Focus NFe; NFe.io's invoice id for NFe.io).
provider	string	optional	Optional explicit provider. Omit to auto-route by credential headers. Overrides header x-invoice-provider.

Raw schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "The ref returned by create_invoice (your ref for Focus NFe; NFe.io's invoice id for NFe.io)."
    },
    "provider": {
      "type": "string",
      "enum": [
        "focusnfe",
        "nfeio"
      ],
      "description": "Optional explicit provider. Omit to auto-route by credential headers. Overrides header x-invoice-provider."
    }
  },
  "required": [
    "ref"
  ]
}

cancel_invoice

Cancel (void) an authorized Brazil NFS-e at the prefeitura, using its ref. Requires a justificativa (cancellation reason) of 15 to 255 characters. Only an AUTHORIZED NFS-e can be canceled; cancellation is permanent.

Parameters3

ref	string	required	The ref returned by create_invoice (your ref for Focus NFe; NFe.io's invoice id for NFe.io).
justificativa	string	required	Reason for cancellation (justificativa), 15-255 characters — required by the prefeitura (Focus NFe). NFe.io cancels without a mandatory reason but this is still collected for parity.
provider	string	optional	Optional explicit provider. Omit to auto-route by credential headers. Overrides header x-invoice-provider.

Raw schema

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "description": "The ref returned by create_invoice (your ref for Focus NFe; NFe.io's invoice id for NFe.io)."
    },
    "justificativa": {
      "type": "string",
      "description": "Reason for cancellation (justificativa), 15-255 characters — required by the prefeitura (Focus NFe). NFe.io cancels without a mandatory reason but this is still collected for parity."
    },
    "provider": {
      "type": "string",
      "enum": [
        "focusnfe",
        "nfeio"
      ],
      "description": "Optional explicit provider. Omit to auto-route by credential headers. Overrides header x-invoice-provider."
    }
  },
  "required": [
    "ref",
    "justificativa"
  ]
}

README.md4 KBView on GitHub

Brazil Invoice MCP 🇧🇷 — How can my AI agent issue an NFS-e (nota fiscal de serviço) in Brazil?

Use it in 60 seconds

Paste this into your MCP client config (Claude Desktop, Cursor, Windsurf, or any MCP-capable agent):

json

{
  "mcpServers": {
    "brazil-invoice": {
      "type": "http",
      "url": "https://inv-br.wishpool.app/mcp"
    }
  }
}

Nothing to install. Credentials, when you need them, travel as HTTP headers on each request and are never stored — see the threat model.

Or run it yourself

Would you rather not send production credentials to a server you do not control? Deploy this identical code to your own account and point your agent at your own URL:

bash

git clone https://github.com/junter1989k-ai/brazil-invoice-mcp && cd brazil-invoice-mcp && npx vercel --prod

MIT-licensed. Self-hosting removes us from the picture entirely, at no cost and with no loss of function.

Remote MCP server that lets any AI agent issue Brazil NFS-e electronic service invoices (nota fiscal de serviço eletrônica, authorized by the municipality/prefeitura) via Focus NFe. Stateless, bring-your-own credentials, never stores anything.

Live endpoint: https://inv-br.wishpool.app/mcp · Registry: app.wishpool/brazil-invoice-mcp

Quick start

json

{
  "mcpServers": {
    "brazil-invoice": {
      "type": "http",
      "url": "https://inv-br.wishpool.app/mcp",
      "headers": { "x-focusnfe-token": "your_homologacao_token" }
    }
  }
}

Free homologação (sandbox) tokens from focusnfe.com.br issue test NFS-e with no fiscal effect. Add "x-focusnfe-mode": "production" with your produção token to issue real ones (sandbox is the default). Your digital certificate and inscrição municipal stay in your own Focus NFe account — this server never sees them.

Tools

Tool	What it does
`create_invoice`	Submit an NFS-e (nota fiscal de serviço) — provider CNPJ + inscrição municipal, buyer name + CPF/CNPJ, `valor_servicos` + `discriminacao` + `item_lista_servico` in, a `ref` out. Async: returns `PROCESSING`; poll `query_invoice`.
`query_invoice`	Status check by `ref`: `PROCESSING`, `AUTHORIZED` (with `numero` + `codigo_verificacao` + `url`), `ERROR` (with message), or `CANCELED`.
`cancel_invoice`	Void an authorized NFS-e at the prefeitura with a `justificativa` (15–255 chars).

Owner policy guardrails ride optional headers (x-agentpay-max-amount, x-agentpay-approval-above, x-agentpay-allowed-tools) — set by the human owner in client config; the agent cannot relax them.

Async flow

NFS-e authorization at the prefeitura is asynchronous. create_invoice returns status: PROCESSING and a ref; call query_invoice with that ref until it reads AUTHORIZED (nota autorizada) or ERROR.

Develop

bash

node test/serve.js   # local server on :3227
node test/e2e.js     # protocol + validation + fake-token live probes (real homologação endpoint)

Safety

Pure stateless translation layer. The prefeitura/SEFAZ authorization burden sits with Focus NFe; credentials travel per-request in headers, nothing is stored. Privacy policy.

Roadmap

v1 covers NFS-e (service invoices) — the fit for digital and service merchants. NF-e (nota fiscal eletrônica for physical goods) is planned for v2.

Sister servers

Mexico CFDI invoices are live: inv-mx.wishpool.app. Local payments in 81 countries, one family: mcp.wishpool.app · Taiwan e-invoice 電子發票 included. More invoice countries coming: Chile DTE · Peru CPE · India GST · Poland KSeF · Romania e-Factura · Italy SdI.

MIT licensed.

Install

Tools (3)

create_invoicequery_invoicecancel_invoice

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://inv-br.wishpool.app/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "brazil-invoice-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://inv-br.wishpool.app/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.