# mcp-nfe-io

MCP server for NFe.io fiscal tools. Issues Brazilian invoices (NF-e and NFS-e) and handles CNPJ and CEP lookups directly from your coding agent.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/fiscal/nfe-io
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-nfe-io

## What it does

This server connects AI assistants to 22 NFe.io endpoints. Your agent can issue service invoices, generate product bills, handle cancellations, and retrieve authorized XML or PDF files. Requests automatically route to the proper NFe.io hostname depending on whether you handle product invoices, services, or registry lookups.

It also handles Brazilian company data inquiries by CNPJ and resolves postal codes to full street addresses. You can provision corporate sub-accounts and register webhook subscriptions for invoice event callbacks. Local pipelines and test workflows can run without network access by passing `--demo` or setting `MCP_DEMO=true` to receive mock payloads.

Live operations will fail without a valid `NFEIO_API_KEY` present in your environment variables. You can provide `NFEIO_COMPANY_ID` once globally or pass an identifier inside specific tool calls.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `NFEIO_API_KEY`, `NFEIO_COMPANY_ID` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env NFEIO_API_KEY=<NFEIO_API_KEY> --env NFEIO_COMPANY_ID=<NFEIO_COMPANY_ID> --transport stdio nfe-io -- npx -y @codespar/mcp-nfe-io
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
codex mcp add nfe-io --env NFEIO_API_KEY=<NFEIO_API_KEY> --env NFEIO_COMPANY_ID=<NFEIO_COMPANY_ID> -- npx -y @codespar/mcp-nfe-io
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "nfe-io": {
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-nfe-io"
            ],
            "env": {
                "NFEIO_API_KEY": "<NFEIO_API_KEY>",
                "NFEIO_COMPANY_ID": "<NFEIO_COMPANY_ID>"
            }
        }
    }
}
```
Replace <…> with your own values

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "nfe-io": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@codespar/mcp-nfe-io"
            ],
            "env": {
                "NFEIO_API_KEY": "<NFEIO_API_KEY>",
                "NFEIO_COMPANY_ID": "<NFEIO_COMPANY_ID>"
            }
        }
    }
}
```
Replace <…> with your own values

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e NFEIO_API_KEY=<NFEIO_API_KEY> -e NFEIO_COMPANY_ID=<NFEIO_COMPANY_ID> nfe-io npx -y @codespar/mcp-nfe-io
```
Replace <…> with your own values

## When to use it
- Generate an NFS-e service invoice directly from agent prompts
- Download the authorized XML and PDF files for a product invoice
- Look up company registration details and legal address using CNPJ
- Register webhook callbacks for incoming invoice events

## Example prompts
- Look up company details for CNPJ 00.000.000/0001-91 with `consult_cnpj`.
- Issue an NFS-e for this order and email the PDF using `email_nfse`.
- Find the postal address for CEP 01310-100 using `consult_cep`.

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md