Stackin

Stackin MCP 插件 — 面向 ChatGPT、Claude Code、Codex 和 Cursor 的 NF-e 与 NFS-e

通过任何支持 Model Context Protocol 的 AI 客户端，签发、查询、更正和取消巴西电子发票（nota fiscal eletrônica）。

---

用自然语言提问——“为这项服务签发一张 NFS-e”、“我的上一张 NF-e 为什么被拒绝？”、 “取消发票 1042，并告诉我原因代码”——模型就会通过 Stackin，与 SEFAZ 和市政 NFS-e Web 服务交互并完成操作。

16 个工具、9 个技能、一个托管服务。 无需安装 SDK，无需签署 XML，也无需在客户端管理证书。

• 🧾 NF-e（货物）和 NFS-e（服务）——签发、查询、取消
• 🔎 根据税务机关自己的代码诊断拒绝原因，并选择重新签发还是更正
• ✉️ 针对已授权 NF-e 的更正函（CC-e）
• 📥 已接收的发票——读取并申报其他公司针对你开具的文件
• 🔢 号码作废——作废已预留但从未使用的 NF-e 号码范围
• 📄 直接在对话中获取 DANFE / DANFSe PDF
• 🔎 税务代码查询——查询 NCM、CFOP 或 CEST，不再靠猜；并确认 CNPJ 的归属方

目录

• 在 Claude Code 中安装
• 在 ChatGPT 和 Codex 中安装
• 从 Cursor 或任何 MCP 客户端连接
• 身份验证：OAuth 或 API 密钥
• 技能
• 本仓库包含的内容
• 一个插件，三个客户端
• MCP Registry
• 常见问题
• 维护者说明

在 Claude Code 中安装

该仓库本身就是一个市场，因此可直接从 GitHub 安装：

claude plugin marketplace add stackin-io/stackin-mcp-plugin
claude plugin install stackin@stackin

该插件包含 9 个技能，并将 Claude Code 指向 https://mcp.stackin.io/mcp。 无需进行任何配置：首次调用工具时会返回带有 WWW-Authenticate 的 401 响应，Claude Code 会自动处理——在会话中运行 /mcp，在打开的浏览器中授权，令牌便会为你保存。客户端会通过 /oauth/register 注册自身，因此无需任何人提供 client_id。

更倾向于使用静态密钥？可以手动添加服务并设置请求头，而不安装插件——请参阅身份验证。

在 ChatGPT 和 Codex 中安装

同一服务也作为 ChatGPT 应用通过 Developer Mode 发布。启用 Developer Mode，将 https://mcp.stackin.io/mcp 注册为连接器并完成授权——含视频的完整操作指南见 docs.stackin.io/mcp。

从 Cursor 或任何 MCP 客户端连接

任何 MCP 客户端都可以直接使用此服务，无需此插件。Cursor 会读取项目中的 .cursor/mcp.json，或 ~/.cursor/mcp.json。其插值语法与 Claude Code 的不同：Cursor 使用 ${env:VAR}。

{
  "mcpServers": {
    "stackin": {
      "url": "https://mcp.stackin.io/mcp",
      "headers": { "Authorization": "Bearer ${env:STACKIN_API_KEY}" }
    }
  }
}

手动配置 Claude Code — ${VAR} 会从环境变量中展开：

claude mcp add --transport http stackin https://mcp.stackin.io/mcp \
  --header "Authorization: Bearer ${STACKIN_API_KEY}"

属性	值
端点	https://mcp.stackin.io/mcp
传输方式	streamable-http
身份验证	使用 PKCE 和动态客户端注册的 OAuth 2.1，或静态 Bearer 密钥
环境	联调环境和生产环境，由密钥或授权连接固定

身份验证：OAuth 或 API 密钥

有两种接入方式，行为各不相同。

使用 API 密钥。 在 app.stackin.io 生成密钥；密钥已包含环境信息，因此无需在客户端中选择环境。将其作为 Authorization: Bearer <key> 发送。

使用 OAuth，无需密钥。 不设置请求头：工具调用会返回 401，并附带指向 /.well-known/oauth-protected-resource 的 WWW-Authenticate，因此运行 /mcp 时，Claude Code 会提示登录。服务支持动态客户端注册（/oauth/register），因此客户端自行注册即可获得 client_id，无需任何人介入。Cursor 也可以在 auth 键下保存静态客户端凭据，而不进行动态注册。

已于 2026-09-09 验证，测试到浏览器阶段：不设置任何请求头即可连接服务；工具调用会返回带有 resource_metadata 挑战的 401；受保护资源文档可以正常解析；/oauth/register 返回 201，且 /oauth/authorize 会重定向到授权同意页面。尚未通过 Claude Code 或 Cursor 完整走通浏览器授权流程——ChatGPT 已完成真实授权，但这两个客户端尚未完成。如果流程中途停止，请检查它使用的 redirect_uri：/oauth/authorize 只接受客户端已注册的 URI。

技能

仅当操作顺序或财税规则能够补充工具描述本身无法涵盖的内容时，才会提供技能。

技能	说明
issue-invoice	根据情况确定所需单据，并在开具前进行验证
consult-invoice	查找单据，以及各项操作所需的标识符
cancel-invoice	在执行不可逆操作前进行确认，以及何时应改用更正函
diagnose-invoice	解读税务机关的拒绝代码，并在重新开具和更正之间做出选择
correct-invoice	为已授权的 NF-e 提交更正函，以及 CC-e 不得更改的内容
invalidate-numbering	声明某个 NF-e 编号段已保留且从未使用
received-invoices	查阅其他公司针对本公司开具的单据，并对其进行回复
fiscal-lookup	开具前查询 NCM、CFOP 或 CEST，而不是凭猜测填写
taxpayer-lookup	确认税号归属，并了解为什么 404 并不代表 CNPJ 无效

此代码库包含的内容

此代码库是分发层：包含清单、技能和资源。服务本身位于 https://mcp.stackin.io/mcp，并使用 Model Context Protocol。

路径	内容
.codex-plugin/plugin.json	插件标识、版本、类别和法律链接
.app.json	将插件映射到已注册的 MCP 连接
.agents/plugins/marketplace.json	本地市场，用于发布前安装
.claude-plugin/plugin.json	Claude Code 的插件标识
.claude-plugin/marketplace.json	可供 Claude Code 添加的本代码库市场
.mcp.json	面向 Claude Code 的托管 MCP 服务
server.json	MCP Registry 条目
skills/	九个需要超出工具描述内容的工作流
assets/	图标和徽标

一个插件，三个客户端

此代码库包含三份清单，因为三个生态系统会在不同位置查找文件，而缺少文件时它们都会静默失败：

客户端	查找位置	读取内容
ChatGPT / Codex	.codex-plugin/plugin.json + .app.json	应用 ID 和托管的 MCP 服务
Codex marketplace	.agents/plugins/marketplace.json	将此代码库作为来源
Claude Code	.claude-plugin/marketplace.json、.claude-plugin/plugin.json、.mcp.json	技能和 https://mcp.stackin.io/mcp

将文件夹添加到 Claude Code 时失败，并显示 "未找到 marketplace 清单…… （预期为 .cursor-plugin/marketplace.json 或 .claude-plugin/marketplace.json）"，直到第三行所列文件存在。技能是共享的：三个客户端都指向 skills/，因此只需编写一次技能，所有客户端都能读取。

MCP Registry

server.json 将托管服务描述为官方 MCP Registry中的远程条目—— io.github.stackin-io/stackin、streamable-http，无需安装软件包。

发布流程已自动化：推送 v* 标签会运行 .github/workflows/publish-mcp.yml，根据标签写入版本，通过 GitHub OIDC 进行身份验证（无需存储令牌——工作流自身的身份会授予 io.github.stackin-io/* 命名空间的权限），然后发布。

git tag v1.0.0 && git push origin v1.0.0

Registry 列出的是公开代码库，因此此条目放在这里，而不是与服务自身的源代码放在一起。

常见问题

客户端需要数字证书（A1/A3）吗？ 不需要。证书只需在 app.stackin.io 上传一次，并保存在服务端。

它能在生产环境中使用，还是只能用于验收环境？ 两者都可以。环境由 API 密钥或通过 OAuth 授权的连接固定；每次调用时无需选择。

NFS-e 支持哪些市政辖区？ Stackin 覆盖的辖区；请参阅 docs.stackin.io。NF-e 则通过 SEFAZ 覆盖全国。

不使用此插件也能使用该服务吗？ 可以——它是一个普通的 MCP 服务。插件只是添加技能，并省去手动配置。

它免费吗？ 开具发票会消耗 Stackin 账户中的额度。查询和取消则不会。

代码查询曾返回 403，现在却不会了。有什么变化？ 在 2026-09-10 之前，这四个路由没有 OAuth scope，因此无论获授权的应用获得了什么权限，都会被拒绝。现在它们需要 invoice:read，而每个连接都已具备此权限——在该日期之前创建的连接无需重新建立。

我知道某个 CNPJ 有效，但 lookup_taxpayer 返回了 404。它有问题吗？ 很可能没有。该登记簿每月根据 Receita Federal 的数据转储重新加载，因此最近几周注册的公司尚未收录其中。它不是有效性检查，也不应因此阻止开具发票。

维护者备注

.app.json 中的 app_id 于 2026-09-06 填写，当时 mcp.stackin.io 已在 OpenAI Developer Mode 中注册，并且真实连接器完成了 OAuth 授权。此前特意留空，因为这是唯一无法提前准备的值。

工具列表过期的问题是通过创建新应用解决的，而不是重新扫描。 第一个应用（asdk_app_6a9d458d…）在 NFS-e 限制生效前就已扫描，因此仍在公布旧版工具集。现在 .app.json 中填写的是第二个应用；如果将来创建第三个应用，需要更新的就是此文件，而且值填错时不会有任何提示。

NF-e 于 2026-09-07 分两步恢复。 首先，document_type 扩展为可在现有八个工具中接受 nfe——单看数量无法发现这项更改。随后，四个仅适用于 NF-e 的操作恢复：correct_invoice、invalidate_numbering、list_received_invoices 和 manifest_received_invoice。随后共有十二个工具、七个技能。

四个查询工具于 2026-09-10 上线：lookup_fiscal_code、search_fiscal_codes、list_fiscal_kinds 和 lookup_taxpayer，以及 fiscal-lookup 和 taxpayer-lookup 技能。现在共有十六个工具、九个技能。它们上线时会拒绝所有 OAuth 令牌，因为其路由没有任何作用域；当天就为它们授予了 invoice:read，因此无需重新连接。

连接器会缓存扫描时的工具列表。 应用于 2026-09-06 10:48 授权，NFS-e 限制则于 12:00 生效，因此 ChatGPT 仍在公布十一个工具，其中包括服务器上已不存在的三个工具。发布新的插件版本并运行 Scan Tools 才能刷新列表；问题不在服务器上，服务器早已正确。测试前请先核对数量：服务器才是准确信息来源，而 scripts/check_skills.py 会实时读取服务器数据。

请从连接器页面读取标识符，不要从 URL 中读取。 地址是 chatgpt.com/plugins/plugin_asdk_app_…，其中的 plugin_ 是路由的一部分，不属于 ID。应填写页面自身的“App ID”字段中的值——asdk_app_…。填错时不会有任何提示：只有提交失败时才会验证。

mcp.authentication 原先填的是 bearer，那是在服务器支持 OAuth 之前写入的。连接器页面现在显示 Authorization used: OAuth，所以此处填写 oauth。OpenAI 发布的文档中没有该字段的枚举值——developers.openai.com/codex/plugins/apps.md 会重定向到 404——因此这是如实描述，而非经过验证的值。如果提交被拒绝，应首先检查这里。

许可证

MIT — 参见 LICENSE。