Mexican Tax & Banking

mx-fiscal-mcp-server

一个 MCP 服务，为 AI Agent 提供墨西哥税务和银行能力：使用真实校验位验证 RFC、CURP、CLABE 和 NSS，读取 CFDI 4.0 发票，向 SAT 查询发票是否仍然有效，并查阅 SAT 代码表。无需 API 密钥、CSD 证书或 PAC 合同。

问 Claude “读取这张发票，告诉我它是否仍然有效”，它就会解析 XML、标注每个 SAT 代码、检查双方的 RFC 和算术计算，并查询 SAT 的公共状态服务，无需你打开三个网页工具。

> Read this CFDI and check it at the SAT

  parse_cfdi(xml="<cfdi:Comprobante …>")

  CFDI A-1042 — 1160.00 MXN
  ✅ Stamped · version 4.0 · Ingreso
  Emisor:   TES150312DX2 ✅  601 — General de Ley Personas Morales
  Receptor: PELJ900521DK2 ✅  G03 — Gastos en general
  ✅ Totals add up: subtotal − discount + transferred − withheld = total

  cfdi_status(xml="<cfdi:Comprobante …>")

  CFDI status — Vigente
  ✅ The invoice exists in the SAT's records and has not been cancelled.
  Es cancelable: Cancelable con aceptación
  EFOS: returned 200 — the issuer is NOT on the SAT's definitive 69-B list.

---

为什么会有这个项目

墨西哥电子发票分为两部分，但此前只有其中一部分有工具支持。

开具和盖章 CFDI 需要 CSD 证书和 PAC 合同。 这部分已经有工具支持——mcp-cfdi-mx （Python）可以完成，而本服务有意不与之竞争。

读取是另一部分，而且无需任何凭证：校验位算法是公开的，SAT 的目录是公开的，每张打印发票二维码背后的发票状态服务也是公开且无需身份验证的。然而，当要求 Agent 验证 RFC 时，它很可能会编造一个正则表达式，把 XAXX010101000 判为无效——这是开给公众的所有发票使用的 RFC，因为它不符合自身的校验位规则。本服务认真做好了读取这一部分。

算术计算来自 mx-identifiers （MIT 许可、零依赖，使用公共测试向量进行了 101 项测试）；CFDI 读取器移植自 ortamarco.me 上运行的工具； SOAP 信封是从 nodecfdi/sat-estado-cfdi 中读取的，而非凭空猜测。它是三个只读、无需密钥的 MCP 服务中的第三个，另外两个是 domain-security-mcp-server 和 seo-geo-mcp-server。

工具

标识符

工具	功能
validate_rfc	验证个人（13 个字符）和企业（12 个字符）的 RFC，使用完整的模 11 校验位，解析字段和出生／成立日期。标记 SAT 通用 RFC，并指出哪些符合算术规则
validate_curp	验证 18 个字符的 CURP，使用基于 37 的校验位；解码出生日期、性别、州（RENAPO 键，不是 INEGI／ISO）和世纪标记
validate_clabe	验证 18 位 CLABE，使用正确的 3-7-1 控制位——每个加权乘积只计入其个位数（9 × 7 = 63 计为 3），而不是许多实现照搬的 Luhn 风格数字求和（6 + 3 = 9）——并提供 Banxico 银行和地区代码
validate_nss	验证 11 位 IMSS 编号及其 Luhn 校验位，并拆分为分区代表处／登记年份／出生年份／序列号
generate_test_data ⭐	生成 1-100 个信息一致的虚构个人或企业：RFC 和 CURP 来源于相同的姓名和出生日期，CLABE 使用真实参与机构的银行，且每个校验位均有效

CFDI

工具	功能
parse_cfdi ⭐	CFDI XML → JSON：包含抬头、开具方、接收方、每个包含转入税和扣缴税的明细项、税额合计，以及 Timbre Fiscal Digital（若不存在则为 null）。为每个目录代码添加标签，验证双方的 RFC，并检查合计的计算是否正确。按本地名称遍历文档，因此适用于任意 PAC 的命名空间前缀。读取 4.0（包括 Pagos 2.0 和 Nómina 文档，但只从补充内容中提取 timbre 和地方税；其余内容会在 findings 中列出）和 3.3（并提供版本警告）；遇到 Retenciones e información de pagos 文档时会拒绝处理，并说明原因
cfdi_status ⭐	查询 SAT 的公开 ConsultaCFDIService SOAP 端点：返回 Estado、EsCancelable、EstatusCancelación 和 ValidaciónEFOS，并以通俗语言解释各项含义。接受四个关键字段，或完整 XML。失败时采取宽容处理：超时设为 10 秒，在超时、网络错误或 5xx 后重试一次（4xx 后不重试）；失败时返回 available: false，绝不抛出异常
cfdi_batch_status	通过同一服务查询最多 25 张发票，尽量减少对服务的影响：最多同时发送两个请求，重复项只查询一次，结果在内存中缓存 10 分钟（服务中断时不缓存），连续两次失败后不再发送新请求。逐项报告错误项，且不消耗请求次数

目录

工具	功能
sat_catalog_lookup	提供 9 个内置代码表——regimen_fiscal、uso_cfdi、forma_pago、metodo_pago、tipo_comprobante、objeto_imp、impuestos、bancos_clabe、estados_curp——支持按精确代码（忽略前导零）查询，或进行不区分重音符号的文本搜索。绝不访问网络

每个工具均为只读，声明了 outputSchema，并返回 structuredContent （由 SDK 验证），以及人类可读的 Markdown（默认格式）或 JSON （response_format="json"）。只有 cfdi_status 和 cfdi_batch_status 标注了 openWorldHint: true：只有这两个工具会访问网络。

资源和提示词

类型	名称	说明
资源	mx-fiscal://catalogs	9 个内置代码表的索引
资源	mx-fiscal://catalog/<name>	单个表（regimen_fiscal、uso_cfdi、……）的 JSON，结构与 sat_catalog_lookup 相同
提示词	review_cfdi	解析发票，在 SAT 查询并如实报告两项结果
提示词	validate_identifiers	对 RFC / CURP / CLABE / NSS 混合列表进行分类和验证
提示词	seed_test_data	为种子文件生成有效的虚构个人或公司数据

诚实说明

这些信息会显示在工具输出中，而不是藏在这里：

• 结构有效不代表已注册。 校验位计算结果正确，只能说明字符串格式正确，仅此而已。只有 SAT 才能确认 RFC 是否已注册；只有 RENAPO 才能确认 CURP 是否属于某个人。本服务不会向它们中的任何一方查询，措辞也绝不会暗示已进行此类查询。
• XAXX010101000 不符合其自身的校验位。 SAT 通过法令指定了面向公众的通用 RFC，而模 11 算法要求校验位为 4，SAT 却填了 0。XEXX010101000（外国居民）则符合校验位要求。工具会将 is_generic 和 check_digit_satisfied 作为单独的字段报告，而不是将两者合并成“有效”。
• 读取 CFDI 不等于验证 CFDI。 parse_cfdi 不会检查数字签名。一张完全可解析的发票仍可能已被取消，也可能完全是伪造的。
• 无法访问 SAT 不代表发票无效。 状态端点不提供 SLA 或状态页面，而且会发生故障。其文档说明每小时最多可处理 200 万次查询，并要求调用方不要增加查询量，因为每次查询都会读取 SAT 的事务数据库。cfdi_status 会降级为 available: false 并附上原因——这描述的是 SAT 的状态，绝不是文档的状态。
• 银行列表只是部分名单。 bancos_clabe 收录了 Banxico 的主要参与机构，而非完整目录；对于未知代码，会报告为未知，而不会编造名称。该工具完全没有附带 plaza 目录，因此会原样返回 plaza 代码。
• EFOS 代码取自 SAT 自己的表格。 SAT 在其Documentación del Servicio de Consulta de CFDI v1.4第 3 节中说明了 ValidacionEFOS：100、101 和 104 表示开票方在 69-B 最终名单中；102 和 103 表示开票方不在名单中，但发票是代表第三方开具的（a cuenta de terceros），且该第三方 RFC 在名单中；200 和 201 表示开票方不在名单中（201 还表示任何第三方都不在名单中）。efos_state 仅描述开票方；efos_third_party_state（listed / not_listed / not_reported / unknown）则描述第三方。字段为空或代码未被文档说明时，会报告为 unknown，并在 validacion_efos 中保留原始代码，绝不会报告为“在名单中”。最高至 1.0.1 的版本会将 102 和 103 报告为开票方在名单中；1.0.2 修复了此问题。
• Bineo CLABE（银行 165）。 1.0.3 要求使用 mx-identifiers ^1.0.1，该版本包含了相应修复。

协议

基于 v2 MCP SDK 构建，因此支持 2026-07-28 修订版（server/discover、不使用 initialize、每个请求都带有 _meta 信封），同时也继续支持 2025 年时代的客户端——Claude Desktop、Claude Code 和 Cursor——且使用同一个服务工厂。入口点负责判断协议时代：stdio 使用 serveStdio(factory)，HTTP 使用默认 legacy: 'stateless' 的 createMcpHandler(factory)。两个方向都没有会话状态，也没有 Mcp-Session-Id。npm run smoke 会在两个时代测试每个工具，并断言每个连接协商使用的协议时代。

由于工具列表是编译时常量，2026 年时代的连接中，tools/list 和 server/discover 会公布真正的一小时 ttlMs 和 cacheScope: 'public'，而不是使用 SDK 保守的 ttlMs: 0。

安装

需要 Node.js 20+。无需克隆——每个 MCP 客户端都可以通过 npx 运行。

在 Claude Code 中使用

claude mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server

在 -- 之前添加 --scope user（适用于你的所有项目）或 --scope project（会写入共享的 .mcp.json）；默认范围仅限当前项目。

与 Claude Desktop 搭配使用

打开 Settings → Developer → Edit Config，并将以下内容添加到 claude_desktop_config.json — 参见 examples/：

{
  "mcpServers": {
    "mx-fiscal": {
      "command": "npx",
      "args": ["-y", "mx-fiscal-mcp-server"]
    }
  }
}

在 Windows 上，使用 "command": "cmd" 和 "args": ["/c", "npx", "-y", "mx-fiscal-mcp-server"]。 重启客户端，然后询问：“为我的种子文件生成 10 个具有有效 RFC 和 CURP 的墨西哥客户。”

与 Cursor 搭配使用

将相同的 JSON 代码块放入 ~/.cursor/mcp.json（适用于每个项目）或 .cursor/mcp.json（仅适用于此项目）。

与 Codex 搭配使用

codex mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server

也可以放在 ~/.codex/config.toml 中（项目级的 .codex/config.toml 也可用）：

[mcp_servers.mx-fiscal]
command = "npx"
args = ["-y", "mx-fiscal-mcp-server"]

自托管（HTTP 传输）

同一服务支持无状态的 Streamable HTTP，适用于远程或多客户端场景。

TRANSPORT=http npx -y mx-fiscal-mcp-server
# POST JSON-RPC to http://127.0.0.1:3000/mcp   ·   health at /healthz

默认情况下安全：它绑定到 127.0.0.1，且只接受 localhost Host 和 Origin 标头，从而阻止网页发起 DNS 重绑定攻击。 若要将其公开 — 例如部署在 Coolify 或 Traefik 后面 — 请明确启用：

变量	默认值	用途
TRANSPORT	stdio	使用 http 提供 Streamable HTTP 服务
PORT	3000	监听端口，范围为 1-65535；其他值会导致服务停止并输出一行提示
HOST	127.0.0.1	绑定地址；使用 0.0.0.0 以接受远程连接
ALLOWED_HOSTS	—	以逗号分隔的主机名，Host 标头可携带这些主机名（例如 mcp.example.com）
ALLOWED_ORIGINS	—	以逗号分隔的来源，允许浏览器从这些来源调用
MCP_AUTH_TOKEN	—	若已设置，每个请求都需要 Authorization: Bearer <token>
MAX_XML_CHARS	2000000	接受的最大 CFDI 字符数
MAX_CONCURRENT_CFDI	4	同时处理的 parse_cfdi / cfdi_status / cfdi_batch_status 调用数量；其余调用会收到重试提示

服务绝不会发送 CORS 标头，因此网页无法跨源读取响应；ALLOWED_ORIGINS 只决定哪些 Origin 标头会被放行至处理程序（没有 Origin 标头的请求，例如来自 MCP 客户端的请求，则始终会放行）。请求正文的大小上限约为 MAX_XML_CHARS 的 1.25 倍。

自托管实例会代表调用方向 SAT 发起请求，因此请勿在未设置 MCP_AUTH_TOKEN 的情况下公开服务：开放的实例可被免费用作中继，导致你的 IP 被限流。使用 Docker 时（镜像会设置 HOST=0.0.0.0）：

docker build -t mx-fiscal-mcp .
docker run -p 3000:3000 -e ALLOWED_HOSTS=mcp.example.com -e MCP_AUTH_TOKEN=change-me mx-fiscal-mcp

开发

npm run dev        # tsx watch (stdio)
npm run typecheck  # tsc --noEmit
npm test           # deterministic offline unit tests, HTTP transport defaults included
npm run smoke      # every tool over the real protocol, on BOTH eras (queries the SAT)
node scripts/smoke-all.mjs --offline   # the same, minus the calls that reach the SAT
npm run inspect    # MCP Inspector against the built server
npm run build      # type-check + emit dist/

工作原理

src/
├── index.ts        # transport selection: serveStdio | createMcpHandler + Express
├── server.ts       # the server FACTORY — registers every tool, holds the instructions
├── schemas.ts      # Zod 4 outputSchema for each tool
├── constants.ts    # the single external host, timeouts, limits
├── format.ts       # markdown/JSON response shaping, findings
├── core/           # pure logic, no MCP coupling — reusable & testable
│   ├── identifiers.ts # reporting layer over mx-identifiers (errors, labels, findings)
│   ├── cfdi.ts        # the CFDI 4.0 reader, ported 1:1 from the web tool
│   ├── sat.ts         # SOAP envelope, expression builder, response interpretation
│   ├── catalogs.ts    # the nine code tables + lookup
│   └── testdata.ts    # fixture generation
└── tools/          # thin MCP wrappers (Zod schemas, descriptions, formatting)

core/ 层不包含任何 MCP 类型，因此同一套逻辑既支持此服务，也支持 Web UI。所有校验位运算都位于 mx-identifiers 中，本项目不会重新实现。

**网络访问范围：**只有一个主机 consultaqr.facturaelectronica.sat.gob.mx，已在 constants.ts 中硬编码。没有任何工具接受调用方提供的 URL，因此无需防范 SSRF。其他七个工具完全不会发起网络请求。

**不可信 XML：**声明了 DOCTYPE 的文档会在解析前被拒绝（CFDI 不会包含 DOCTYPE）；大小和元素数量上限会限制单次解析可能占用的内存；结果中的属性值会截断至 4,000 个字符。cfdi_status 会先检查 RFC、总额和 UUID，再为其发起请求。发现问题？请提交私密安全公告。

---

西班牙语

一个 MCP 服务，为 AI Agent 提供墨西哥税务能力——这些能力人人都会重新实现，却总是实现得不对：使用真正的校验位验证 RFC、CURP、CLABE 和 NSS，以 XML 格式读取 CFDI 4.0，查询其在 SAT 的状态，并搜索 SAT 的目录。无需 API 密钥、CSD 或 PAC。

**这是读取功能的一半。**要创建并签署 CFDI，需要数字印章证书和 PAC，这部分已有 mcp-cfdi-mx（Python）负责。此服务并不与它竞争，而是与之互补。

它真正擅长、而且几乎无人做到的事：

• **XAXX010101000 不符合自身的校验位。**SAT 通过法令指定了这个值，而模 11 算法要求校验位为 4，SAT 给出的却是 0。XEXX010101000（外国居民）则符合校验位。因此，许多表单会拒绝面向公众的发票。工具会分别返回 is_generic 和 check_digit_satisfied。
• CLABE 的控制位取每个 3-7-1 加权乘积的最后一位，而不是各位数字之和。9 × 7 = 63 应取 3；照搬 Luhn 算法的实现会把 6 + 3 = 9 相加，得出另一个校验位：对于基数 09000000000000000，该算法得出 7，而 Luhn 风格算法得出 1。在求和前或求和后取模 10，结果都一样；错误不在这里。
• CURP 的实体代码来自 RENAPO，而不是 INEGI 或 ISO 3166-2:MX。DF 是墨西哥城，MC 是墨西哥州，NE 表示在国外出生。
• **SAT 服务会宕机，也没有公布 SLA。**其文档声明每小时最多可处理 200 万次查询，并要求不要增加查询量，因为每次查询都会访问其事务数据库。cfdi_status 会降级为 available: false 并说明原因；它绝不会抛出异常，也绝不能把 SAT 故障解读为“发票无效”。
• **结构上有效不等于已注册。**校验位匹配只说明字符串格式正确，仅此而已。

无需克隆任何内容即可安装：claude mcp add mx-fiscal -- npx -y mx-fiscal-mcp-server。

算术引擎是 mx-identifiers（MIT，无依赖）；CFDI 读取器来自运行于 ortamarco.me 的工具；SOAP 信封参考了 nodecfdi/sat-estado-cfdi 的代码，并非凭空编造。

它遵循 2026-07-28 版协议，并通过同一个服务器工厂继续支持 2025 年的客户端（Claude Desktop、Claude Code、Cursor）。

许可证

MIT © Marco Orta