mcp-nuvem-fiscal — Claude Code MCP server: Brazilian fiscal documents
An MCP server that connects your agent to Nuvem Fiscal for issuing NF-e, NFS-e, NFC-e, CT-e and MDF-e, plus CNPJ and CEP lookups.
claude mcp add mcp-nuvem-fiscal -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscalWhat mcp-nuvem-fiscal does
The server talks to Nuvem Fiscal over OAuth2 client credentials and refreshes the token on its own. Your agent gets 24 tools, among them create_nfe, get_nfe, cancel_nfe, create_nfse, get_nfse, cancel_nfse, create_nfce, cancel_nfce, create_cte, get_cte, cancel_cte, create_mdfe, get_mdfe, cancel_mdfe, close_mdfe, consult_cnpj, consult_cep, register_company, list_empresas, upload_certificate, get_nfe_events, get_nfe_batch, send_correction_letter_nfe and send_correction_letter_cte. That covers issuing a document, cancelling it, filing a correction letter, or uploading an A1 certificate as base64 .pfx.
Both NUVEM_FISCAL_CLIENT_ID and NUVEM_FISCAL_CLIENT_SECRET are required. No credentials, no auth — you get them from the Nuvem Fiscal Developer Portal after registering an application. There is also MCP_DEMO=true (or the --demo flag): the server skips the API entirely and serves fixtures, which works for offline walkthroughs and integration smoke tests.
Nuvem Fiscal offers a homologation environment (ambiente=2), so you can emit documents for testing without touching the real tax system. The package ships under the MIT license.
What it helps with
- issue an NF-e from order data
- cancel an NFS-e that was already issued
- resolve a street address from a CEP
- look up a company by its CNPJ
- upload an A1 certificate for a company on the account
Example prompts for the agent
- Issue an NF-e for this order and return the document ID
- Look up the address for CEP 01310-100
- Cancel the NFS-e with this ID and show me the status
How to install mcp-nuvem-fiscal
Platform CLI
claude mcp add mcp-nuvem-fiscal -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscalReplace <…> with your own values
Platform CLI
codex mcp add nuvem-fiscal --env NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscalReplace <…> with your own values
Config file
{
"mcpServers": {
"nuvem-fiscal": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-nuvem-fiscal"
],
"env": {
"NUVEM_FISCAL_CLIENT_SECRET": "<NUVEM_FISCAL_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"nuvem-fiscal": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-nuvem-fiscal"
],
"env": {
"NUVEM_FISCAL_CLIENT_SECRET": "<NUVEM_FISCAL_CLIENT_SECRET>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> nuvem-fiscal npx -y @codespar/mcp-nuvem-fiscalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-nuvem-fiscal
How do I install mcp-nuvem-fiscal in Claude Code?
Run claude mcp add mcp-nuvem-fiscal -e NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> -- npx -y @codespar/mcp-nuvem-fiscal. Alternatively use claude mcp add --env NUVEM_FISCAL_CLIENT_SECRET=<NUVEM_FISCAL_CLIENT_SECRET> --transport stdio nuvem-fiscal -- npx -y @codespar/mcp-nuvem-fiscal.
What does mcp-nuvem-fiscal do?
It exposes Nuvem Fiscal tools to your agent: issuing and cancelling NF-e, NFS-e, NFC-e, CT-e and MDF-e documents, plus CNPJ and CEP lookups.
Can I test the server without hitting the API?
Yes. With MCP_DEMO=true or the --demo flag the server runs on fixtures. In that mode create_nfse returns a distinct fixture ID per call and echoes back the servico.codigo, valor and servico.descricao you sent.
