mcp-cfdi-mx

mcp-cfdi-mx 🇲🇽

English | Español

一个 Python MCP 服务，提供符合 SAT《Anexo 20》技术标准的墨西哥电子发票工具，支持 CFDI 4.0 和 Complemento de Pagos 2.0。它使 AI Agent（Claude、IDE）能够构建、通过 XSD 验证并为 CFDI 4.0 文档（Ingreso、Egreso 和 Complemento de Pagos 2.0）加盖数字印章，验证 PAC 返回的 Timbre Fiscal Digital 印章，并验证墨西哥 RFC 纳税人识别号。

第一阶段范围。 此软件包仅支持 CFDI 4.0 Ingreso、Egreso 和 Complemento de Pagos 2.0，目前尚不支持 Carta Porte、Complemento de Nómina、Retenciones 和 Comercio Exterior，也不会提交给任何 PAC。有关目前实现的具体功能，请参阅可用工具。

---

简介

此软件包基于 mcp-einvoicing-core 构建，这是电子发票 MCP 服务的共享基础库。它提供 InvoiceDocument 模型基类、TaxIdentifier.validate_mx_rfc RFC 验证器，以及 SelloDigitalSigner——core 文档签名抽象的墨西哥专用具体实现（根据 SAT《Anexo 20》，对 cadena original 计算 SHA-256 摘要，并使用 emisor 的 CSD 进行 RSA-PKCS#1v1.5 签名）。

mcp-einvoicing-core 会作为依赖项自动安装，无需额外操作。

CFDI 是一种清关模式标准：只有 PAC（Proveedor Autorizado de Certificación）对 CFDI 进行认证并返回 Timbre Fiscal Digital（TFD）后，该 CFDI 才具有法律效力。此软件包不会提交给 PAC，因而与 PAC 无关；它可以生成本地加盖数字印章的 CFDI（可提交给任何接受预先加盖印章文档的 PAC），也可以生成未加盖印章但通过架构验证的 CFDI（供代表 emisor 加盖印章的 PAC 使用），通过 sealing_mode 参数选择。

安装

通过 PyPI 安装（推荐）

pip install mcp-cfdi-mx

也可以使用 uvx，无需预先安装：

uvx mcp-cfdi-mx

从源代码安装

git clone https://github.com/cmendezs/mcp-cfdi-mx.git
cd mcp-cfdi-mx
uv sync --all-extras

配置（环境变量）

此软件包不需要任何环境变量。CSD 证书／密钥路径和密码作为工具参数传入（文件路径或环境变量引用——绝不会将明文密钥材料嵌入请求），而非从固定名称的环境变量中读取。

Claude Desktop 集成

将以下配置添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "cfdi-mx": {
      "command": "uvx",
      "args": ["mcp-cfdi-mx"]
    }
  }
}

Cursor 集成

Cursor 通过 stdio 支持 MCP 服务。将配置添加到：

• 全局（所有项目）：~/.cursor/mcp.json
• 按项目（仅此仓库）：.cursor/mcp.json

{
  "mcpServers": {
    "cfdi-mx": {
      "command": "uvx",
      "args": ["mcp-cfdi-mx"]
    }
  }
}

保存更改后，重新加载 Cursor 窗口（Ctrl+Shift+P → 重新加载窗口）。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务：

• 全局：~/.kiro/settings/mcp.json
• 工作区：.kiro/settings/mcp.json

{
  "mcpServers": {
    "cfdi-mx": {
      "command": "uvx",
      "args": ["mcp-cfdi-mx"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

安全提示：如果未来版本的工具支持通过环境变量引用传递凭据， 请使用语法 "VAR_NAME": "${VAR_NAME}"，以便 Kiro 从 shell 中解析该值，而不是 将其以明文形式存储。

可用工具

构建

工具	描述
mx__build_cfdi	根据结构化输入构建格式正确、未加盖印章的 CFDI 4.0 Comprobante XML（Ingreso 或 Egreso）
mx__build_pago	构建 Complemento de Pagos 2.0 CFDI（TipoDeComprobante="P"），并按 SAT 指南要求组合固定的单个 Concepto 封装结构

验证和密封

工具	描述
mx__validate_cfdi	根据 cfdv40.xsd 进行完整的 XSD 验证；存在相应附加组件时，还会根据 TimbreFiscalDigitalv11.xsd.xml 和／或 Pagos20.xsd.xml 验证
mx__seal_cfdi	通过 SelloDigitalSigner 计算数字印章，并根据 sealing_mode 选择模式（"local" | "pac"）
mx__verify_tfd	解析 PAC 返回的 1.1 版 Timbre Fiscal Digital 印章；提供 PAC 的证书时，还会以密码学方式验证 SelloSAT

支持范围

工具	描述
mx__get_supported_scope	返回此软件包当前支持的 CFDI 文档类型、附加组件和密封模式

参阅 docs/TOOLS.md，查看根据实时工具注册表生成的所有工具完整参数参考。

尚未实现

PAC 提交传输（此软件包与 PAC 无关，不会向任何特定 PAC 提交），以及后续阶段的附加组件（Carta Porte、Complemento de Nómina、Retenciones、Comercio Exterior）。

架构

mcp_cfdi_mx.models.CFDIComprobante 扩展自 mcp_einvoicing_core.models.InvoiceDocument（非 EN 16931 路径——CFDI 早于 CEN TC 434，且与其没有渊源；这与 mcp-nfe-br 的判断相同）。Emisor 和 Receptor 的 RFC 验证均通过核心模块中的 TaxIdentifier.validate_mx_rfc 进行。密封操作通过 mcp_einvoicing_core.digital_signature.SelloDigitalSigner 完成；它是核心模块 BaseDocumentSigner 的墨西哥专用具体实现——ES（XAdES）、BR（XML-DSig）和 IT（CAdES）也采用相同模式来实现各自的签名标准。

[ ERP System / Application ] <--> [ MCP Server ] <--> [ PAC (any, PAC-agnostic) / SAT ]
          ^                           |
          |                           v
   [ AI Agent (Claude) ] <--- (CFDI 4.0 / Pagos 2.0)

供应商中立性

此服务实现标准本身：在本地构建、验证并签署文档。它不是商业开票平台的客户端，您的签名密钥和凭证也绝不会离开您自己的基础设施。

PAC（Proveedor Autorizado de Certificación，授权认证服务商）必须为 CFDI 加盖印章；此服务会使用您自己的 CSD 在本地密封文档，并将已密封的文档交给任何 PAC。

支持的标准

标准	版本	来源
CFDI（Comprobante Fiscal Digital por Internet）	4.0	SAT Anexo 20，DOF 2022-01-13
Timbre Fiscal Digital	1.1	SAT
Complemento de Pagos	2.0	SAT

参阅 specs/README.md，了解完整的源文件包和获取日期。

测试

uv run pytest tests/ -v

贡献

欢迎贡献——请参阅 CONTRIBUTING.md 了解指南。

其他电子发票 MCP 服务

国家／地区	服务
🌍 全球	mcp-einvoicing-core
🇧🇪 比利时	mcp-einvoicing-be
🇧🇷 巴西	mcp-nfe-br
🇫🇷 法国	mcp-facture-electronique-fr
🇩🇪 德国	mcp-einvoicing-de
🇮🇳 印度	mcp-einvoicing-in
🇮🇹 意大利	mcp-fattura-elettronica-it
🇲🇽 墨西哥	mcp-cfdi-mx
🇵🇱 波兰	mcp-ksef-pl
🇸🇬 新加坡	mcp-invoicenow-sg
🇪🇸 西班牙	mcp-facturacion-electronica-es
🇦🇪 阿拉伯联合酋长国	mcp-einvoicing-ae

许可证

本项目采用 Apache 2.0 许可证发布。 详情请参阅 LICENSE 文件。完整版本历史请参阅 CHANGELOG.md。