mcp-nfe-io

@codespar/mcp-nfe-io

MCP server for NFe.io — NF-e / NFS-e fiscal document emission plus CNPJ and CEP lookups for Brazil.

Quick Start

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nfe-io": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nfe-io"],
      "env": {
        "NFEIO_API_KEY": "your-api-key",
        "NFEIO_COMPANY_ID": "your-company-id-or-cnpj"
      }
    }
  }
}

Claude Code

claude mcp add nfe-io -- npx @codespar/mcp-nfe-io

Cursor / VS Code

Add to .cursor/mcp.json or .vscode/mcp.json:

{
  "servers": {
    "nfe-io": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nfe-io"],
      "env": {
        "NFEIO_API_KEY": "your-api-key",
        "NFEIO_COMPANY_ID": "your-company-id-or-cnpj"
      }
    }
  }
}

Tools (22)

Tool	Purpose
create_nfse	Issue an NFS-e (service invoice).
get_nfse	Fetch a single NFS-e by id.
cancel_nfse	Cancel an NFS-e.
list_nfse	List NFS-e with pagination + optional flowStatus filter.
email_nfse	Email the PDF of an already-issued NFS-e to a recipient.
create_nfe	Issue an NF-e (product invoice).
get_nfe	Fetch a single NF-e by id.
cancel_nfe	Cancel an NF-e.
list_nfe	List NF-e with pagination + optional status filter.
get_nfe_pdf	Return the DANFE PDF URL for an issued NF-e.
consult_cnpj	Look up Brazilian company data (razão social, status, address) by CNPJ.
consult_cep	Resolve a Brazilian postal code (CEP) to a full address.
correct_nfe	Issue a Carta de Correção (CC-e) for an authorized NF-e.
get_nfe_xml	Return the authorized XML URL for an NF-e.
get_nfse_pdf	Return the PDF URL for an issued NFS-e.
get_nfse_xml	Return the XML URL for an issued NFS-e.
list_companies	List companies registered on the NFe.io account.
get_company	Fetch a single company by id or CNPJ.
create_company	Provision a new company on NFe.io.
list_webhooks	List webhook endpoints registered for a company (invoice event callbacks).
create_webhook	Register a webhook endpoint.
delete_webhook	Remove a webhook endpoint by id.

Environment

Variable	Required	Notes
NFEIO_API_KEY	yes	Issuance + query scopes. NFe.io supports splitting this into two keys; either is fine.
NFEIO_COMPANY_ID	no	Default company id (or CNPJ). Per-call company_id arguments override it.

Hosts

NFe.io segments its API across three hostnames. This server maps tools to the correct one automatically:

• api.nfse.io — product invoices
• api.nfe.io — service invoices + company management
• nfe.api.nfe.io — lookups (CNPJ, CEP)

Demo mode

Pass --demo or set MCP_DEMO=true to return canned responses without hitting the network. Useful for documentation, screencasts, and CI.

Links

• NFe.io REST API docs
• CodeSpar MCP Brazil catalog

Enterprise

Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.

Authentication

Set these environment variables before launching the server:

• NFEIO_API_KEY (required, secret) — API key for NFe.io (issuance + query)
• NFEIO_COMPANY_ID — Default company ID (CNPJ or NFe.io company UUID) to use when not provided per-call

Issue credentials at the provider's developer portal: https://nfe.io/docs.

License

MIT