mcp-nuvem-fiscal

@codespar/mcp-nuvem-fiscal

MCP server for Nuvem Fiscal — NFe, NFSe, NFCe fiscal document emission and CNPJ/CEP lookup

Quick Start

Claude Desktop

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

{
  "mcpServers": {
    "nuvem-fiscal": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nuvem-fiscal"],
      "env": {
        "NUVEM_FISCAL_CLIENT_ID": "your-client-id",
        "NUVEM_FISCAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Claude Code

claude mcp add nuvem-fiscal -- npx @codespar/mcp-nuvem-fiscal

Cursor / VS Code

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

{
  "servers": {
    "nuvem-fiscal": {
      "command": "npx",
      "args": ["-y", "@codespar/mcp-nuvem-fiscal"],
      "env": {
        "NUVEM_FISCAL_CLIENT_ID": "your-client-id",
        "NUVEM_FISCAL_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Tools (24)

Tool	Purpose
create_nfe	Create a NF-e (nota fiscal eletrônica)
get_nfe	Get NF-e details by ID
cancel_nfe	Cancel a NF-e
create_nfse	Create a NFS-e (nota fiscal de serviço eletrônica)
get_nfse	Get NFS-e details by ID
cancel_nfse	Cancel a NFS-e
create_nfce	Create a NFC-e (nota fiscal de consumidor eletrônica)
consult_cnpj	Consult company data by CNPJ number
consult_cep	Consult address by CEP (postal code)
register_company	Register a company in Nuvem Fiscal
create_cte	Create a CT-e (conhecimento de transporte eletrônico)
get_cte	Get CT-e details by ID
cancel_cte	Cancel a CT-e
create_mdfe	Create a MDF-e (manifesto de documentos fiscais eletrônico)
get_nfe_events	Get events for a NF-e (cancellations, corrections, etc.)
cancel_nfce	Cancel a NFC-e (nota fiscal de consumidor eletrônica)
send_correction_letter_nfe	Send a carta de correção eletrônica (CCe) for a NF-e.
send_correction_letter_cte	Send a carta de correção for a CT-e.
get_nfe_batch	Get NF-e batch (lote) status by batch ID.
get_mdfe	Get MDF-e details by ID
cancel_mdfe	Cancel a MDF-e (manifesto)
close_mdfe	Close (encerrar) a MDF-e at route end.
list_empresas	List all companies (empresas) registered in the account.
upload_certificate	Upload or update an A1 digital certificate (.pfx, base64) for an empresa.

Authentication

Nuvem Fiscal uses OAuth2 client credentials. The server automatically manages token refresh.

Sandbox / Testing

Nuvem Fiscal supports a homologation environment (ambiente=2) for testing fiscal document emission without affecting real tax systems.

Demo Mode

Set MCP_DEMO=true (or pass --demo) to run the server without contacting the Nuvem Fiscal API. In MCP_DEMO=true mode, create_nfse issues distinct fixture IDs per call within one process and echoes input servico.codigo, valor, and servico.descricao into the response. pdf_url is templated from the fixture id. Other demo tools return static fixtures and are useful for offline walkthroughs and integration smoke tests.

Get your credentials

1. Go to Nuvem Fiscal Developer Portal
2. Create an account
3. Register an application to get OAuth2 credentials
4. Set the environment variables

Environment Variables

Variable	Required	Description
NUVEM_FISCAL_CLIENT_ID	Yes	OAuth2 client ID
NUVEM_FISCAL_CLIENT_SECRET	Yes	OAuth2 client secret

Roadmap

v0.2 (planned)

• create_cte — Create a CT-e (electronic transport document)
• get_cte — Get CT-e details by ID
• cancel_cte — Cancel an issued CT-e
• create_mdfe — Create an MDF-e (electronic freight manifest)
• get_nfe_events — Get events for an NF-e (cancellation, correction, etc.)

v0.3 (planned)

• batch_nfe — Create multiple NF-e in a single request
• get_nfe_danfe — Get DANFE PDF for an NF-e
• manifest_recipient — Manifest recipient awareness of an NF-e

Want to contribute? Open a PR or request a tool.

Links

• Nuvem Fiscal Website
• Nuvem Fiscal API Documentation
• MCP Dev LATAM
• Landing Page

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.

License

MIT