mcp-nuvem-fiscal

@codespar/mcp-nuvem-fiscal

面向 Nuvem Fiscal 的 MCP 服务 — 开具 NFe、NFSe、NFCe 财政文档，以及查询 CNPJ/CEP

快速开始

Claude Desktop

添加到 ~/.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

添加到 .cursor/mcp.json 或 .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"
      }
    }
  }
}

工具（24 个）

工具	用途
create_nfe	创建 NF-e（电子税务发票）
get_nfe	根据 ID 获取 NF-e 详情
cancel_nfe	取消 NF-e
create_nfse	创建 NFS-e（电子服务税务发票）
get_nfse	根据 ID 获取 NFS-e 详情
cancel_nfse	取消 NFS-e
create_nfce	创建 NFC-e（电子消费者税务发票）
consult_cnpj	根据 CNPJ 编号查询公司数据
consult_cep	根据 CEP（邮政编码）查询地址
register_company	在 Nuvem Fiscal 注册公司
create_cte	创建 CT-e（电子运输单据）
get_cte	根据 ID 获取 CT-e 详情
cancel_cte	取消 CT-e
create_mdfe	创建 MDF-e（电子税务单据清单）
get_nfe_events	获取 NF-e 的事件（取消、更正等）
cancel_nfce	取消 NFC-e（电子消费者税务发票）
send_correction_letter_nfe	为 NF-e 发送电子更正函（CCe）。
send_correction_letter_cte	为 CT-e 发送更正函。
get_nfe_batch	根据批次 ID 获取 NF-e 批次（lote）状态。
get_mdfe	根据 ID 获取 MDF-e 详情
cancel_mdfe	取消 MDF-e（manifesto）
close_mdfe	在路线终点关闭（encerrar）MDF-e。
list_empresas	列出账户中注册的所有公司（empresas）。
upload_certificate	为 empresa 上传或更新 A1 数字证书（.pfx，base64）。

身份验证

Nuvem Fiscal 使用 OAuth2 客户端凭据。服务会自动管理令牌刷新。

沙盒 / 测试

Nuvem Fiscal 提供 homologation 测试环境（ambiente=2），可用于测试开具财政文档，而不会影响实际税务系统。

演示模式

设置 MCP_DEMO=true（或传入 --demo），即可在不连接 Nuvem Fiscal API 的情况下运行服务。在 MCP_DEMO=true 模式下，create_nfse 会在单个进程中为每次调用生成不同的 fixture ID，并将输入的 servico.codigo、valor 和 servico.descricao 回显到响应中。pdf_url 根据 fixture ID 生成。其他演示工具会返回静态 fixture，适用于离线演示和集成冒烟测试。

获取凭据

1. 前往 Nuvem Fiscal 开发者门户
2. 创建账户
3. 注册应用以获取 OAuth2 凭据
4. 设置环境变量

环境变量

变量	必需	描述
NUVEM_FISCAL_CLIENT_ID	是	OAuth2 客户端 ID
NUVEM_FISCAL_CLIENT_SECRET	是	OAuth2 客户端密钥

路线图

v0.2（计划中）

• create_cte — 创建 CT-e（电子运输单据）
• get_cte — 根据 ID 获取 CT-e 详情
• cancel_cte — 取消已开具的 CT-e
• create_mdfe — 创建 MDF-e（电子货运清单）
• get_nfe_events — 获取 NF-e 的事件（取消、更正等）

v0.3（计划中）

• batch_nfe — 在单个请求中创建多张 NF-e
• get_nfe_danfe — 获取 NF-e 的 DANFE PDF
• manifest_recipient — 确认收件人已知悉 NF-e

想要贡献？提交 PR 或请求添加工具。

链接

• Nuvem Fiscal 网站
• Nuvem Fiscal API 文档
• MCP Dev LATAM
• 落地页

企业版

需要对 Agent 付款进行治理、设置预算限额并保留审计跟踪？CodeSpar Enterprise 在这些 MCP 服务的基础上，增加策略引擎、支付路由和合规模板。

许可证

MIT