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

<!-- install-cta -->
## 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](https://mcp.wishpool.app/trust).

### 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:

[![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/junter1989k-ai/brazil-invoice-mcp)

```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](https://focusnfe.com.br). 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](https://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](https://inv-br.wishpool.app/privacy).

## 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](https://inv-mx.wishpool.app). Local payments in 81 countries, one family: [mcp.wishpool.app](https://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.