@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"
}
}
}
}
| 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
- Go to Nuvem Fiscal Developer Portal
- Create an account
- Register an application to get OAuth2 credentials
- 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 IDcancel_cte — Cancel an issued CT-ecreate_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 requestget_nfe_danfe — Get DANFE PDF for an NF-emanifest_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