Mcp Nuvem Fiscal

io.github.codesparPublished by GitHub account codesparv0.3.1Updated Oct 24, 2026

MCP server for Nuvem Fiscal — NF-e, NFS-e, NFC-e, CNPJ, CEP

VerifiedSTDIODesktop onlyFinanceBusiness & Commerce

Overview

AI-generated overview

Local MCP server for Nuvem Fiscal that lets an assistant issue, query and cancel Brazilian electronic fiscal documents and look up CNPJ and CEP data.

What you can do
Create, retrieve and cancel NF-e, NFS-e, NFC-e, CT-e and MDF-e fiscal documents, including closing MDF-e and checking NF-e batch status and events. Send correction letters (CCe) for NF-e and CT-e. Look up company data by CNPJ and addresses by CEP. Register companies and upload A1 digital certificates for them. List companies registered in the account.
When to use it
Useful when an assistant should help with Brazilian tax and invoicing workflows through Nuvem Fiscal: issuing or cancelling fiscal documents, correcting them, or looking up CNPJ and CEP data. Test in the homologation environment or demo mode before touching real tax systems.
Requirements
Runs locally via npx (Node.js). Needs a Nuvem Fiscal account and OAuth2 client credentials supplied as the environment variables NUVEM_FISCAL_CLIENT_ID and NUVEM_FISCAL_CLIENT_SECRET; network access to the Nuvem Fiscal API. Demo mode can run offline with MCP_DEMO=true or --demo.
Before you install
The server can create, cancel and correct real fiscal documents and register companies, so mistakes affect actual tax records; use the homologation environment or demo mode first. It handles OAuth2 client credentials and A1 digital certificates (.pfx), which are sensitive secrets. Document data is sent to the Nuvem Fiscal API.

Installation

In SourceWeft

  1. Open Mcp Nuvem Fiscal in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

@codespar/mcp-nuvem-fiscal

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

[npm] [License: MIT]

Quick Start

Claude Desktop

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

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

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

Cursor / VS Code

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

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)

ToolPurpose
create_nfeCreate a NF-e (nota fiscal eletrônica)
get_nfeGet NF-e details by ID
cancel_nfeCancel a NF-e
create_nfseCreate a NFS-e (nota fiscal de serviço eletrônica)
get_nfseGet NFS-e details by ID
cancel_nfseCancel a NFS-e
create_nfceCreate a NFC-e (nota fiscal de consumidor eletrônica)
consult_cnpjConsult company data by CNPJ number
consult_cepConsult address by CEP (postal code)
register_companyRegister a company in Nuvem Fiscal
create_cteCreate a CT-e (conhecimento de transporte eletrônico)
get_cteGet CT-e details by ID
cancel_cteCancel a CT-e
create_mdfeCreate a MDF-e (manifesto de documentos fiscais eletrônico)
get_nfe_eventsGet events for a NF-e (cancellations, corrections, etc.)
cancel_nfceCancel a NFC-e (nota fiscal de consumidor eletrônica)
send_correction_letter_nfeSend a carta de correção eletrônica (CCe) for a NF-e.
send_correction_letter_cteSend a carta de correção for a CT-e.
get_nfe_batchGet NF-e batch (lote) status by batch ID.
get_mdfeGet MDF-e details by ID
cancel_mdfeCancel a MDF-e (manifesto)
close_mdfeClose (encerrar) a MDF-e at route end.
list_empresasList all companies (empresas) registered in the account.
upload_certificateUpload 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

VariableRequiredDescription
NUVEM_FISCAL_CLIENT_IDYesOAuth2 client ID
NUVEM_FISCAL_CLIENT_SECRETYesOAuth2 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

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

Source: packages/fiscal/nuvem-fiscal/README.md at commit d0a519a

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts