Mcp Nuvem Fiscal

io.github.codespar由 GitHub 账号 codespar 发布v0.3.1更新于 Oct 24, 2026

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

已验证STDIO仅桌面金融商业与电商

概览

AI 生成的概览

面向 Nuvem Fiscal 的本地 MCP 服务器，让助手开具、查询和取消巴西电子税务单据，并查询 CNPJ 和 CEP 信息。

可以做什么
创建、查询和取消 NF-e、NFS-e、NFC-e、CT-e 和 MDF-e 税务单据，包括关闭 MDF-e、查询 NF-e 批次状态和事件。为 NF-e 和 CT-e 发送更正函（CCe）。按 CNPJ 查询公司信息，按 CEP 查询地址。注册公司并为其上传 A1 数字证书。列出账户中已注册的公司。
适用场景
适合需要助手通过 Nuvem Fiscal 处理巴西税务和开票流程的场景：开具或取消税务单据、发送更正函，或查询 CNPJ 与 CEP 数据。在接触真实税务系统前，先在 homologation 环境或演示模式下测试。
运行要求
通过 npx 在本地运行（需要 Node.js）。需要 Nuvem Fiscal 账户和 OAuth2 客户端凭据，通过环境变量 NUVEM_FISCAL_CLIENT_ID 和 NUVEM_FISCAL_CLIENT_SECRET 提供；需要访问 Nuvem Fiscal API 的网络。设置 MCP_DEMO=true 或 --demo 可离线运行演示模式。
安装前请注意
该服务器可创建、取消和更正真实税务单据并注册公司，操作失误会影响实际税务记录，建议先在 homologation 环境或演示模式中试用。它涉及 OAuth2 客户端凭据和 A1 数字证书（.pfx）等敏感机密。单据数据会发送到 Nuvem Fiscal API。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Mcp Nuvem Fiscal，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

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

来源：packages/fiscal/nuvem-fiscal/README.md，提交 d0a519a

工具

0
SourceWeft 尚未在沙箱中启动过该软件包，因此其工具未知。

版本历史

1
  1. v0.3.1最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分