nota-fiscal-mcp

Name: nota-fiscal-mcp
Author: FAVIOSENGER

本地服务

github.com/FAVIOSENGER金融数据02 周前更新

代码仓库

关于 nota-fiscal-mcp

nota-fiscal-mcp 通过 Focus NFe 为 AI Agent 提供巴西 NF-e 和 NFS-e 的开具、查询与取消能力。它由使用者运行并连接自己的服务商账户，也可通过模拟模式测试工具。

主要功能

01开具 NFS-e
02查询 NFS-e 状态及文件链接
03取消已授权 NFS-e
04开具 NF-e
05查询 NF-e 状态及下载
06取消 NF-e

适用场景

01为服务开具 NFS-e
02查询税票状态并获取 XML 或 PDF
03取消已授权的 NFS-e
04通过模拟模式测试开票流程

MCP 相关

该 MCP 服务向 Claude Desktop、Claude Code、Cursor 等客户端开放 NF-e 和 NFS-e 的开具、查询与取消工具。它通过 Focus NFe 提供商处理税务服务，凭据通过环境变量配置。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "faviosenger-nota-fiscal": {
      "command": "npx",
      "args": [
        "-y",
        "nota-fiscal-mcp"
      ],
      "env": {
        "FOCUS_NFE_TOKEN": "<FOCUS_NFE_TOKEN>",
        "FOCUS_NFE_AMBIENTE": "<FOCUS_NFE_AMBIENTE>"
      }
    }
  }
}

启动命令npx -y nota-fiscal-mcp

需要配置的环境变量

FOCUS_NFE_TOKEN密钥Token da conta Focus NFe (homologacao ou producao).

FOCUS_NFE_AMBIENTEAmbiente: 'homologacao' (padrao) ou 'producao'.

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmnota-fiscal-mcp0.1.2stdio

工具

收录的工具列表 · 更新于 2 周前

参数	类型	必填	说明
ref	string	是	为发票选择的唯一标识符（例如 `'pedido-1023'`）。
dados	object	是	包含服务提供商格式的 NFS-e 税务数据的对象。

详细介绍

🧾 nota-fiscal-mcp

让 AI 为你开具发票。

nota-fiscal-mcp 是一个 MCP 服务，赋予任何 AI Agent——Claude Desktop、Claude Code、Cursor 等——在巴西开具、查询和取消 NF-e 与 NFS-e 的能力。它会与税务服务提供商（Focus NFe）通信，由该服务商处理复杂工作：数字证书、与 SEFAZ 及市政府的通信。

你来对话。AI 来开票。

Você:   emita uma NFS-e de R$ 500 de consultoria em TI para o cliente ACME
Claude: ✅ NFS-e emitida — nota nº 3070, autorizada. Aqui está o PDF e o XML.

无需打开系统，无需填写表单，也无需记住 ISS 字段。

✨ 它能做什么

工具	功能
`emitir_nfse`	开具服务发票（NFS-e）
`consultar_nfse`	查询 NFS-e 的状态和链接（XML/PDF）
`cancelar_nfse`	取消已获批准的 NFS-e
`emitir_nfe`	开具产品发票（NF-e，型号 55）
`consultar_nfe`	查询 NF-e 状态并下载文件
`cancelar_nfe`	取消 NF-e（开具后 24 小时内）

AI 负责组装发票的税务内容；服务负责身份验证、引用信息以及与服务提供商的通信。

🚀 安装

无需克隆或编译任何内容——此软件包可通过 npx 直接运行。

Claude Desktop

打开配置文件（claude_desktop_config.json）并添加：

{
  "mcpServers": {
    "nota-fiscal": {
      "command": "npx",
      "args": ["-y", "nota-fiscal-mcp"],
      "env": {
        "FOCUS_NFE_TOKEN": "seu_token_aqui",
        "FOCUS_NFE_AMBIENTE": "homologacao"
      }
    }
  }
}

重启 Claude Desktop。完成后，Agent 就能使用这 6 个工具。

任何 MCP 客户端（Claude Code、Cursor 等）的配置方法都相同：只需使用环境变量指定命令 npx -y nota-fiscal-mcp。

🔑 前置条件：税务服务提供商账户

要实际开具发票，你需要税务服务提供商提供的令牌。目前，nota-fiscal-mcp 使用 Focus NFe，它提供测试环境（homologação），并替你处理数字证书和 SEFAZ。

在 Focus NFe 创建账户。
注册你的公司并获取测试令牌（在 API 面板 → 令牌 中）。
将令牌填入上述配置并尽情测试——测试环境不会开具具有税务效力的发票。
确认一切正常后，将 FOCUS_NFE_AMBIENTE 改为 producao，并使用正式环境令牌。

⚙️ 环境变量

变量	必填	说明
`FOCUS_NFE_TOKEN`	是	你的 Focus NFe 账户令牌
`FOCUS_NFE_AMBIENTE`	否	`homologacao`（默认）或 `producao`

🧪 模拟模式（无需服务提供商）

想在没有令牌的情况下测试工作流程？以模拟模式运行——它会伪造响应，让你完整体验这 6 个工具：

"env": { "PROVIDER": "mock" }

🔒 安全

将令牌放在环境变量中——绝不要把它写进代码或上传到代码仓库。
始终从测试环境开始。验证完成后再切换到正式环境。
本项目是开源的：使用你自己的账户和自己的令牌运行。所有操作都不会经过第三方服务器。

🛠️ 开发

git clone https://github.com/FAVIOSENGER/nota-fiscal-mcp.git
cd nota-fiscal-mcp
npm install
npm run build
PROVIDER=mock node test/client.mjs   # testa as 6 ferramentas em simulação