mcp-facturacion-electronica-es

Name: mcp-facturacion-electronica-es
Author: cmendezs

本地服务

github.com/cmendezs金融数据27 周前更新

代码仓库

关于 mcp-facturacion-electronica-es

mcp-facturacion-electronica-es 是面向西班牙电子发票流程的 MCP 服务，可生成、验证并提交多种国家及地区体系下的发票记录。它为需要处理 VERI*FACTU、Facturae/FACe、SII 等规范的企业工作流提供工具。

主要功能

01生成并校验 VERI*FACTU 记录
02提交记录并查询状态
03生成发票二维码
04生成发票作废记录
05支持西班牙多种电子发票体系

适用场景

01准备 VERI*FACTU 发票记录
02检查发票 XML 结构
03向 AEAT 提交记录并跟踪状态

MCP 相关

该项目是 MCP 服务，向兼容客户端提供西班牙电子发票的生成、验证、提交及查询工具。

配置

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

mcp.json · 通用配置

{
  "mcpServers": {
    "cmendezs-mcp-facturacion-electronica-es": {
      "command": "uvx",
      "args": [
        "mcp-facturacion-electronica-es"
      ],
      "env": {
        "AEAT_ENV": "<AEAT_ENV>",
        "AEAT_CERTIFICATE_PATH": "<AEAT_CERTIFICATE_PATH>",
        "AEAT_CERTIFICATE_PASSWORD": "<AEAT_CERTIFICATE_PASSWORD>",
        "AEAT_NIF": "<AEAT_NIF>",
        "FACE_ENV": "<FACE_ENV>",
        "LOG_LEVEL": "<LOG_LEVEL>"
      }
    }
  }
}

启动命令uvx mcp-facturacion-electronica-es

需要配置的环境变量

AEAT_ENVTarget environment for AEAT endpoints: 'sandbox' or 'production'.

AEAT_CERTIFICATE_PATHFilesystem path to the FNMT-RCM PKCS#12 certificate (.p12 / .pfx) used for MTLS submission to AEAT (VERI*FACTU and SII) and for JWS-signed FACe submission.

AEAT_CERTIFICATE_PASSWORD密钥Passphrase for the PKCS#12 certificate at AEAT_CERTIFICATE_PATH.

AEAT_NIFTaxpayer NIF used as the default submitter identity for AEAT submissions.

FACE_ENVTarget environment for FACe API: 'sandbox' or 'production'.

LOG_LEVELLogging level inherited from mcp-einvoicing-core: DEBUG, INFO (default), WARNING, or ERROR.

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

安装包

pypimcp-facturacion-electronica-es0.10.1stdio

工具

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

参数	类型	必填	说明
invoice	object	是	发票数据（date、number、seller、buyer、vat_summary、note）。
impuesto	string	否	税种代码（默认为 '01' IVA）。
software_id	string	是	认证软件的 IDSistemaInformatico。
invoice_type	string	否	根据 HAC/1177/2024 Annex I 的 TipoFactura （F1、F2、F3、R1、R2、R3、R4、R5）。
software_nif	string	是	软件制造商的 NIF。
clave_regimen	string	否	ClaveRegimenEspecialOTrascendencia（默认为 '01'）。
previous_hash	any	否	前一条记录的 SHA-256 Huella（第一条记录时省略）。
previous_fecha	any	否	上一条记录的 FechaExpedicionFactura，格式为 DD-MM-YYYY （存在 previous_hash 时必填）。
previous_num_serie	any	否	上一条记录的 NumSerieFactura（存在 previous_hash 时必填）。
previous_emisor_nif	any	否	上一条记录的 NIF emisor（存在 previous_hash 时必填）。
calificacion_operacion	string	否	CalificacionOperacion（默认为 'S1'）。

详细介绍

mcp-facturacion-electronica-es 🇪🇸

English | 西班牙语

简介

mcp-facturacion-electronica-es 是一款专用于西班牙电子发票的 MCP（模型上下文协议）服务。它提供用于生成、验证和提交电子发票的工具，支持西班牙并行运行的六种体系：VERI*FACTU、Facturae/FACe、SII、TicketBAI（巴斯克地区）、NaTicket（纳瓦拉），以及《第 18/2022 号法律》（“Crea y Crece”）规定的 B2B 义务。该服务基于 mcp-einvoicing-core 构建，该共享基础库也用于 mcp-facture-electronique-fr（法国，XP Z12-013）和 mcp-einvoicing-be（比利时，Peppol BIS 3.0），提供通用模型、验证抽象、XML 工具和异常层级。mcp-einvoicing-core 会作为传递依赖自动安装，无需额外操作。

西班牙的电子发票体系是欧洲最复杂的体系之一，有六种重叠的制度，具体适用规则取决于纳税人规模、行业和地区。VERI*FACTU（第 1007/2023 号皇家法令、第 HAC/1177/2024 号命令）将成为面向非 SII 纳税人的强制实时发票登记系统，截止日期分别为 2027 年 1 月和 7 月（第 15/2025 号皇家法令法）。SII（Suministro Inmediato de Informacion，即时信息报送）已适用于大型纳税人（营业额超过 600 万欧元）。巴斯克地区实施 TicketBAI，纳瓦拉实施 NaTicket，两者均独立于国家税务局 AEAT 框架。自 2015 年起，通过 FACe 门户使用 Facturae XML 进行 B2G 开票已成为强制要求（第 25/2013 号法律）。

安装

从 PyPI 安装（推荐）

pip install mcp-facturacion-electronica-es

无需预先安装，使用 uvx：

uvx mcp-facturacion-electronica-es

从源代码安装

git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git
cd mcp-facturacion-electronica-es
uv sync --all-extras

配置

所有配置均通过环境变量或 .env 文件完成。

AEAT / VERI*FACTU / SII

变量	描述	必填
`AEAT_ENV`	`sandbox` 或 `production`	是
`AEAT_CERTIFICATE_PATH`	FNMT-RCM PKCS#12 证书路径	提交时需要
`AEAT_CERTIFICATE_PASSWORD`	证书密码	提交时需要
`AEAT_NIF`	纳税人 NIF	提交时需要

FACe

变量	描述	必填
`FACE_ENV`	`sandbox` 或 `production`	是

FACe 使用 JWS 进行身份验证，证书与 VERI*FACTU/SII 使用的 AEAT_CERTIFICATE_PATH / AEAT_CERTIFICATE_PASSWORD 相同（见上文 AEAT 部分）；无需单独的 FACe 凭据。

TicketBAI

变量	描述	必填
`TICKETBAI_ENV`	`sandbox` 或 `production`	是
`TICKETBAI_CERTIFICATE_PATH`	省级签名证书路径	是
`TICKETBAI_CERTIFICATE_PASSWORD`	证书密码	是

通用（继承自 `mcp-einvoicing-core`）

变量	描述	默认值
`LOG_LEVEL`	`DEBUG`、`INFO`、`WARNING`、`ERROR`	`INFO`

Claude Desktop 集成

要在 Claude 中使用此服务，请将以下配置添加到 claude_desktop_config.json 文件中：

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "certificate-password"
      }
    }
  }
}

Cursor 集成

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

全局（所有项目）：~/.cursor/mcp.json
项目（仅此代码库）：.cursor/mcp.json

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "certificate-password"
      }
    }
  }
}

重新加载 Cursor 窗口（按 Ctrl+Shift+P，然后选择 Reload Window）以应用更改。

Kiro 集成

Kiro 通过专用配置文件支持 MCP 服务。有两个级别可供选择：

全局（所有项目）：~/.kiro/settings/mcp.json
工作区（仅此代码库）：.kiro/settings/mcp.json

{
  "mcpServers": {
    "facturacion-es": {
      "command": "uvx",
      "args": ["mcp-facturacion-electronica-es"],
      "env": {
        "AEAT_ENV": "sandbox",
        "AEAT_CERTIFICATE_PATH": "/path/to/cert.p12",
        "AEAT_CERTIFICATE_PASSWORD": "certificate-password"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

保存后，文件会自动重新加载。你也可以通过命令面板（Cmd+Shift+P / Ctrl+Shift+P）打开配置，然后选择 MCP。

Kiro 安全提示：不要以纯文本形式写入密钥，而应使用语法 "AEAT_CERTIFICATE_PASSWORD": "${AEAT_CERTIFICATE_PASSWORD}"。Kiro 会在启动时解析 shell 环境变量。

可用工具

VERI*FACTU

`es__generate_verifactu_record`

生成防篡改发票记录（Orden HAC/1177/2024），并使用 SHA-256 Huella 链将其与上一条记录关联。

参数	类型	必填	描述
`invoice`	`InvoiceDocument`	是	发票核心模型（卖方、买方、明细、增值税）
`previous_hash`	`string`	否	前一条记录的 SHA-256 `Huella`（`null` = 链中的第一条记录）
`software_id`	`string`	是	认证软件的 `IDSistemaInformatico`
`software_nif`	`string`	是	软件制造商的 NIF
`invoice_type`	`string`	是	`F1`、`F2`、`R1`–`R5` 或 `F3`

{
  "tool": "es__generate_verifactu_record",
  "arguments": {
    "invoice": { "date": "2025-03-15", "number": "2025-0042", "currency": "EUR",
      "seller": { "tax_id": { "country_code": "ES", "identifier": "B12345678" }, "name": "Empresa SL" },
      "buyer":  { "tax_id": { "country_code": "ES", "identifier": "A98765432" }, "name": "Cliente SA" },
      "lines": [{ "line_number": 1, "description": "Servicios", "quantity": 10, "unit_price": 100.00, "vat_rate": 21.0 }]
    },
    "previous_hash": "3C4A9B...", "software_id": "SW-001", "software_nif": "B87654321", "invoice_type": "F1"
  }
}

Huella 链接算法（对由键值 campo=valor& 组成的规范字符串计算 SHA-256）已通过 AEAT 自身的 huella 规范及其示例（specs/verifactu/documentation/Veri-Factu_especificaciones_huella_hash_registros.pdf）逐字节验证。 ⚠️ 尚待完成：通过实时 AEAT 测试环境的确认回执，对完整 XSD v1.0 进行验证。

`es__validate_verifactu_record`

根据随 Orden HAC/1177/2024 发布的官方 XSD（BOE-A-2024-22138）验证 VERI*FACTU XML 记录。

参数	类型	必填	描述
`xml`	`string`	是	原始 VERI*FACTU XML 记录
`schema_version`	`string`	否	架构版本（默认值：`"1.0"`）

{ "tool": "es__validate_verifactu_record", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>" } }

结构检查现在会根据 RegistroAlta 和 RegistroAnulacion 正确分支处理（先前版本会错误地将有效的 RegistroAnulacion 文档标记为缺少 TipoFactura/CuotaTotal/ImporteTotal，这些字段仅适用于 RegistroAlta）。完整的 XSD 模式验证（SuministroLR.xsd，随附于 resources/verifactu/）在运行时需要网络访问——该架构会通过远程 URL 导入 W3C xmldsig-core 架构；如果无法解析该导入，则会回退到上述结构检查。

`es__submit_verifactu_to_aeat`

通过 MTLS（FNMT-RCM Class 1 证书）将已签名的 VERI*FACTU 记录提交到 AEAT 实时端点；如果配置了 EINVOICING_SIGNER_SOCKET，则通过签名器微服务提交。遵循 AEAT_ENV=sandbox|production 设置。提交端点（.../SistemaFacturacion/VerifactuSOAP）已根据 AEAT 官方 WSDL 确认，且由 alta/anulación 提交操作和 es__query_verifactu_status 查询操作共同使用。

参数	类型	必填	描述
`xml`	`string`	是	已签名的 VERI*FACTU XML
`nif`	`string`	是	发送方 NIF

{ "tool": "es__submit_verifactu_to_aeat", "arguments": { "xml": "<RegistroFacturacion>...</RegistroFacturacion>", "nif": "B12345678" } }

响应包含一个 chain 对象，用于实现仅接受记录才可入链的约定：只有当 AEAT 的 EstadoRegistro 为 Correcto 或 AceptadoConErrores 时，才会填充 chain.safe_to_chain_from（即所提交记录自身的 emisor_nif/num_serie/fecha/huella）——这两种状态都表示记录已通过该 Huella 实际存储。否则，safe_to_chain_from 为 null，并附有明确的 warning，提示不要将此记录的 Huella 用作下一条记录的 previous_hash；若结果为 deferred，则会附有 note，提示先调用 es__query_verifactu_status。

`es__generate_qr_verifactu`

生成符合 VERI*FACTU 要求的 QR 码（HAC/1177/2024 第 10 条），并输出为 base64 编码的 PNG。编码 AEAT 验证 URL，并附带文本“可在 AEAT 电子办事处验证的发票”。可考虑将其推广到 mcp-einvoicing-core（QR 码生成）。 URL 格式（主机、路径、nif/numserie/fecha/importe 查询参数，以及各参数的 URL 编码方式）已根据 AEAT 官方 QR 码规范（specs/verifactu/documentation/DetalleEspecificacTecnCodigoQRfactura.pdf）确认；URL 会根据 AEAT_ENV 在沙盒和生产环境的 ValidarQR 主机之间切换。

参数	类型	必填	描述
`nif`	`string`	是	开票方 NIF
`invoice_number`	`string`	是	`NumSerieFactura`
`invoice_date`	`string`	是	`FechaExpedicionFactura`（YYYY-MM-DD）
`total_amount`	`number`	是	含 VAT 的发票总额
`size_px`	`integer`	否	QR 码尺寸（像素）（默认值：200）

{ "tool": "es__generate_qr_verifactu", "arguments": { "nif": "B12345678", "invoice_number": "2025-0042", "invoice_date": "2025-03-15", "total_amount": 1210.00 } }

`es__cancel_verifactu_record`

生成 VERI*FACTU 作废记录（RegistroAnulacion，TipoHuella=01），并将其链接到当前指纹序列。作废记录的 Huella（对 IDEmisorFacturaAnulada/NumSerieFacturaAnulada/FechaExpedicionFacturaAnulada/Huella/ FechaHoraHusoGenRegistro 计算 SHA-256——这组字段与 RegistroAlta 的字段不同，并非其精简副本）以及顶层 <IDFactura> 块的元素名称，均已根据 AEAT 官方指纹规范和 SuministroInformacion.xsd 确认。

参数	类型	必填	描述
`original_invoice_number`	`string`	是	要作废的 `NumSerieFactura`
`original_invoice_date`	`string`	是	`FechaExpedicionFactura`（YYYY-MM-DD）
`issuer_nif`	`string`	是	开票方 NIF
`previous_hash`	`string`	是	链中最后一条记录的 `Huella`

{ "tool": "es__cancel_verifactu_record", "arguments": { "original_invoice_number": "2025-0042", "original_invoice_date": "2025-03-15", "issuer_nif": "B12345678", "previous_hash": "3C4A9B..." } }

`es__query_verifactu_status`

查询已提交的 VERI*FACTU 记录的 EstadoRegistro （ConsultaFactuSistemaFacturacion / ConsultaLR.xsd）。当 es__submit_verifactu_to_aeat 返回 deferred 结果后使用：等待 retry_after_seconds，然后调用此工具确认最终状态（Correcto / AceptadoConErrores / Anulado），再链接下一条记录。与 es__submit_verifactu_to_aeat 一样，需要设置 AEAT_ENV、AEAT_CERTIFICATE_PATH 和 AEAT_CERTIFICATE_PASSWORD。

参数	类型	必填	描述
`nif`	`string`	是	`ObligadoEmision` 的 NIF
`name`	`string`	是	`ObligadoEmision` 的名称/法定名称
`invoice_date`	`string`	是	要查询的发票日期，`YYYY-MM-DD`（用于确定 `PeriodoImputacion`）
`num_serie_factura`	`string`	否	`NumSerieFactura` 筛选条件（省略则查询整个期间）

{ "tool": "es__query_verifactu_status", "arguments": { "nif": "B12345678", "name": "Empresa SL", "invoice_date": "2025-03-15", "num_serie_factura": "2025-0042" } }

根元素名称（ConsultaFactuSistemaFacturacion）和端点——即 es__submit_verifactu_to_aeat 使用的同一 .../SistemaFacturacion/VerifactuSOAP URL——均已根据官方 WSDL 确认。⚠️ 尚待完成：尚未通过 AEAT 沙盒的实际确认响应验证响应解析。

Facturae / FACe

`es__generate_facturae_xml`

生成符合 Facturae 3.2.2 标准、用于 B2G 提交的 XML 发票。使用 mcp-einvoicing-core 中的 InvoiceDocument。

参数	类型	必填	说明
`invoice`	`InvoiceDocument`	是	核心发票模型
`schema_version`	`string`	否	Facturae 架构版本（默认值：`"3.2.2"`）
`tax_type`	`string`	否	间接税制度：`IVA`（半岛地区/巴利阿里群岛）、`IPSI`（休达/梅利利亚）或 `IGIC`（加那利群岛）。不支持在同一张发票上混用税种。默认值：`"IVA"`
`recargo_equivalencia_rate`	`number`	否	Recargo de Equivalencia 税率（%），如适用
`recargo_equivalencia_amount`	`number`	否	明确指定的 Recargo de Equivalencia 金额；如省略，则按 `base_imponible * recargo_equivalencia_rate / 100` 计算
`irpf_rate`	`number`	否	IRPF 预扣税率（%），在 `TaxesWithheld` 中输出

{ "tool": "es__generate_facturae_xml", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042", "seller": { "tax_id": { "country_code": "ES", "identifier": "B12345678" }, "name": "Proveedor SL" }, "buyer": { "tax_id": { "country_code": "ES", "identifier": "S2800000D" }, "name": "Ayuntamiento de Madrid" }, "lines": [{ "line_number": 1, "description": "Suministro", "quantity": 5, "unit_price": 200.00, "vat_rate": 21.0 }] } } }

⚠️ 等待监管确认

`es__sign_facturae_xades`

对 Facturae XML 文档应用 XAdES-EPES 数字签名（ETSI EN 319 132-1）。建议迁移至 mcp-einvoicing-core（XAdES 签名，评分 3/3）。

参数	类型	必填	说明
`xml`	`string`	是	未签名的 Facturae XML
`cert_path`	`string`	是	PKCS#12 证书路径（`.p12` / `.pfx`）
`signature_policy_id`	`string`	否	签名策略 OID（默认使用 Facturae 标准）

不接受将证书密码作为工具参数（ES-SH-6，以避免在 LLM 上下文/日志中暴露明文凭据）；请改为设置 AEAT_CERTIFICATE_PASSWORD。

{ "tool": "es__sign_facturae_xades", "arguments": { "xml": "<Facturae>...</Facturae>", "cert_path": "/certs/empresa.p12" } }

⚠️ 等待监管确认

`es__submit_to_face`

通过 FACe 集成方 REST API，将已签名的 Facturae XML 提交至 FACe（Punto General de Entrada de Facturas Electronicas）。按照 FACe-manual-api-integradores.pdf 第 2.3 节，使用 JWS 签名的 JWT（RS256，x5c 标头）进行身份验证；该 JWT 使用与 VERI*FACTU/SII 相同的 AEAT_CERTIFICATE_PATH / AEAT_CERTIFICATE_PASSWORD 证书生成。

参数	类型	必填	说明
`xml`	`string`	是	带有 XAdES 签名的 Facturae XML
`administrative_unit`	`string`	是	FACe `UnidadTramitadora` 代码
`accounting_office`	`string`	是	FACe `OficinasContables` 代码
`management_body`	`string`	是	FACe `OrganoGestor` 代码

{ "tool": "es__submit_to_face", "arguments": { "xml": "<Facturae>...</Facturae>", "administrative_unit": "U00000038", "accounting_office": "U00000038", "management_body": "U00000038" } }

⚠️ 等待监管确认

`es__get_face_invoice_status`

查询发票在 FACe 上的处理状态。返回标准状态代码： 1200（已登记）、2400（已确认）、3100（已拒绝）、4100（已付款）。不会将 FACe 的原始响应回传给 LLM；仅返回结构化且不含敏感信息的子集（status_code、codigo、descripcion、numeroRegistro）（ES-SH-7）。

参数	类型	必填	说明
`invoice_id`	`string`	是	FACe 登记号码

{ "tool": "es__get_face_invoice_status", "arguments": { "invoice_id": "FAC-2025-00012345" } }

⚠️ 等待监管确认

`es__validate_facturae_schema`

针对 Facturae XML 运行结构字段检查清单，然后使用 lxml 尝试根据官方 Facturae 3.2.2 架构执行完整的 XSD 模式验证。

参数	类型	必填	说明
`xml`	`string`	是	要验证的 Facturae XML
`schema_version`	`string`	否	架构版本（默认值：`"3.2.2"`）

{ "tool": "es__validate_facturae_schema", "arguments": { "xml": "<Facturae>...</Facturae>" } }

完整的 XSD 模式验证（Facturaev3_2_2.xml，随附于 resources/facturae/）需要在运行时访问网络——该文件通过远程 URL 导入 W3C xmldsig-core 架构；如果无法解析该导入，则回退到上述结构检查。

⚠️ 等待监管确认

SII（Suministro Inmediato de Informacion）

`es__build_sii_invoice_record`

构建符合 AEAT SII 技术指南 v3.0（2024 年 4 月）的 AEAT SII XML 记录（已开具的 FacturaExpedida 或已收到的 FacturaRecibida）。支持 TipoComunicacion A0/A1/A4。

参数	类型	必填	描述
`invoice`	`InvoiceDocument`	是	发票核心模型
`record_type`	`string`	是	`"issued"` 或 `"received"`
`communication_type`	`string`	否	`"A0"` 新增（默认值）、`"A1"` 修改、`"A4"` 作废

{ "tool": "es__build_sii_invoice_record", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "record_type": "issued", "communication_type": "A0" } }

⚠️ 等待监管部门确认

`es__submit_sii_batch`

向 AEAT SII SOAP 端点提交一批发票（最多 10,000 条记录）。需要 MTLS。

参数	类型	必填	描述
`records`	`array`	是	来自 `es__build_sii_invoice_record` 的 XML 字符串列表
`record_type`	`string`	是	`"issued"` 或 `"received"`
`fiscal_year`	`integer`	是	财政年度（YYYY）

{ "tool": "es__submit_sii_batch", "arguments": { "records": ["<RegistroLRFacturasEmitidas>...</RegistroLRFacturasEmitidas>"], "record_type": "issued", "fiscal_year": 2025 } }

⚠️ 等待监管部门确认：AuthMode.MTLS 尚未在 mcp-einvoicing-core 中实现。

`es__query_sii_status`

通过 ConsultaFactInformadasEmitidas 或 ConsultaFactInformadasRecibidas 查询已提交的 SII 批次状态。

参数	类型	必填	描述
`nif_titular`	`string`	是	SII 责任人（obligado tributario）的 NIF
`nombre_titular`	`string`	是	责任人的姓名或公司名称
`fiscal_year`	`integer`	是	财政年度（YYYY）
`period`	`string`	是	结算期间：月度为 `"01"`..`"12"`，年度为 `"0A"`
`record_type`	`string`	否	`"issued"` 或 `"received"`（默认值：`"issued"`）
`invoice_number`	`string`	否	`NumSerieFacturaEmisor`，用于筛选特定发票
`emisor_nif`	`string`	否	用于筛选的开票方 NIF（仅适用于 `"received"`）

{ "tool": "es__query_sii_status", "arguments": { "nif_titular": "B12345674", "nombre_titular": "Ejemplo SL", "fiscal_year": 2025, "period": "03", "record_type": "issued" } }

⚠️ 等待监管部门确认

`es__generate_sii_correction`

生成引用原始发票的 SII 修改（A1）或作废（A4）记录，引用方式为 IDFactura。贷项通知单构建器是 mcp-einvoicing-core 的候选功能（评分 3/3）。

参数	类型	必填	描述
`original_invoice`	`InvoiceDocument`	是	正在更正的发票
`corrected_invoice`	`InvoiceDocument`	否	更正后的数据（A4 时为 `null`）
`correction_type`	`string`	是	`"A1"` 或 `"A4"`
`record_type`	`string`	是	`"issued"` 或 `"received"`

{ "tool": "es__generate_sii_correction", "arguments": { "original_invoice": { "number": "2025-0042" }, "correction_type": "A1", "record_type": "issued" } }

⚠️ 等待监管部门确认

TicketBAI

`es__generate_ticketbai_xml`

生成带有 XAdES 签名和 HuellaTBAI 链的 TicketBAI XML 发票。自动选择对应省份的 XSD：Araba v1.2、Gipuzkoa v1.2、Bizkaia v2.1。

参数	类型	必填	描述
`invoice`	`InvoiceDocument`	是	发票核心模型
`province`	`string`	是	`"araba"`、`"gipuzkoa"` 或 `"bizkaia"`
`previous_hash`	`string`	否	上一条记录的 `HuellaTBAI`
`software_license`	`string`	是	TicketBAI 软件许可证密钥
`cert_path`	`string`	是	签名证书路径
`cert_password`	`string`	是	证书密码

{ "tool": "es__generate_ticketbai_xml", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "province": "gipuzkoa", "software_license": "TBAI-GI-12345", "cert_path": "/certs/empresa.p12", "cert_password": "s3cr3t" } }

⚠️ 等待监管部门确认：三个省份的 XSD 必须分别打包；不允许跨省验证。

`es__submit_ticketbai`

向相应的巴斯克省级主管机构提交 TicketBAI XML 记录。端点会自动路由：Araba（batuz.eus）、Gipuzkoa（tbai.egoitza.gipuzkoa.eus）、Bizkaia（www.bizkaia.eus/ogasun）。

参数	类型	必填	描述
`xml`	`string`	是	已签名的 TicketBAI XML
`province`	`string`	是	`"araba"`、`"gipuzkoa"` 或 `"bizkaia"`
`nif`	`string`	是	发送方 NIF

{ "tool": "es__submit_ticketbai", "arguments": { "xml": "<T:TicketBai>...</T:TicketBai>", "province": "bizkaia", "nif": "B12345678" } }

⚠️ 等待监管部门确认

`es__validate_ticketbai_schema`

根据正确的省级 XSD 验证 TicketBAI XML 文档。不同省份的架构不可互换。

参数	类型	必填	描述
`xml`	`string`	是	TicketBAI XML
`province`	`string`	是	`"araba"`、`"gipuzkoa"` 或 `"bizkaia"`

{ "tool": "es__validate_ticketbai_schema", "arguments": { "xml": "<T:TicketBai>...</T:TicketBai>", "province": "gipuzkoa" } }

⚠️ 待监管部门确认

Crea y Crece / B2B

`es__generate_b2b_einvoice_es`

根据 Ley 18/2022 生成符合 EN 16931 的 B2B 发票，格式为 UBL 2.1 或 Facturae 3.2.2；该法由 RD 238/2026 (BOE-A-2026-7295) 制定。

参数	类型	必填	描述
`invoice`	`InvoiceDocument`	是	核心发票模型
`format`	`string`	否	`"ubl"`（默认）或 `"facturae"`

{ "tool": "es__generate_b2b_einvoice_es", "arguments": { "invoice": { "date": "2025-03-15", "number": "2025-0042" }, "format": "ubl" } }

⚠️ RD 238/2026 确认了认可的格式（EN 16931：CII/UBL/EDIFACT/Facturae；此工具实现 UBL 和 Facturae）。制定公共解决方案技术规范（Disp. final tercera）的 Orden Ministerial (Hacienda) 仍待发布。

`es__check_b2b_mandate_applicability`

根据营业额、省份代码和 SII 登记情况确定适用制度（VERI*FACTU、SII、TicketBAI、NaTicket）。应用 Real Decreto 254/2025 中的互斥逻辑。

参数	类型	必填	描述
`annual_turnover_eur`	`number`	是	年度增值税营业额，单位为 EUR
`tax_address_province_code`	`string`	是	INE 省份代码（例如，马德里的代码为 `"28"`）
`enrolled_in_sii`	`boolean`	否	SII 登记情况（默认值：`false`）
`entity_type`	`string`	否	`"IS"`（Impuesto sobre Sociedades）或 `"IRPF"`

{ "tool": "es__check_b2b_mandate_applicability", "arguments": { "annual_turnover_eur": 2500000, "tax_address_province_code": "28", "enrolled_in_sii": false, "entity_type": "IS" } }

⚠️ 待监管部门确认

实用工具

`es__detect_regional_regime`

根据 INE 省份代码检测适用的电子发票制度。返回 VERIFACTU、TICKETBAI、NATICKET 或 VERIFACTU+SII。

巴斯克省份：01 Araba、20 Gipuzkoa、48 Bizkaia。纳瓦拉：31。其他省份均返回 VERIFACTU。可考虑提升至 mcp-einvoicing-core。

参数	类型	必填	描述
`province_code`	`string`	是	两位数 INE 省份代码
`enrolled_in_sii`	`boolean`	否	SII 登记情况（默认值：`false`）

{ "tool": "es__detect_regional_regime", "arguments": { "province_code": "20", "enrolled_in_sii": false } }

⚠️ 待监管部门确认

`es__get_compliance_status`

返回适用于企业档案的当前强制要求截止日期和运行制度。反映 RD-ley 15/2025，但后续法律法规可能会对其进行修改。可考虑提升至 mcp-einvoicing-core（通用截止日期注册表）。

参数	类型	必填	描述
`entity_type`	`string`	是	`"IS"` 或 `"IRPF"`
`province_code`	`string`	是	INE 省份代码
`annual_turnover_eur`	`number`	否	用于 SII 门槛检查（6M EUR）
`enrolled_in_sii`	`boolean`	否	SII 登记情况

{ "tool": "es__get_compliance_status", "arguments": { "entity_type": "IS", "province_code": "28", "annual_turnover_eur": 1000000, "enrolled_in_sii": false } }

⚠️ 待监管部门确认

`es__parse_aeat_response`

将 AEAT XML 响应（VERI*FACTU 或 SII）解析并规范化为结构化 JSON。提取 EstadoEnvio（Correcto/AceptadoConErrores/Incorrecto）、CSV（安全验证码）和错误详情。可考虑提升至 mcp-einvoicing-core（通用供应商 XML 响应解析器，评分 2/3）。

参数	类型	必填	描述
`xml`	`string`	是	原始 AEAT XML 响应
`response_type`	`string`	否	`"verifactu"`（默认）或 `"sii"`

{ "tool": "es__parse_aeat_response", "arguments": { "xml": "<RespuestaRegFactuSistemaFacturacion>...</RespuestaRegFactuSistemaFacturacion>", "response_type": "verifactu" } }

⚠️ 待监管部门确认

架构

mcp-facturacion-electronica-es 是 mcp-einvoicing 系列中的国家适配器，基于 mcp-einvoicing-core 构建。

mcp-einvoicing-core (v0.1.0+)
│   BaseDocumentGenerator, BaseDocumentValidator, BaseLifecycleManager
│   InvoiceDocument, InvoiceParty, InvoiceLineItem, VATSummary, PaymentTerms
│   EInvoicingError, ValidationError, XSDValidationError, PlatformError
│   BaseEInvoicingClient, OAuthConfig, AuthMode (OAUTH2 / BEARER / MTLS)
│   get_logger, format_amount, xml_element, format_error
│
├── mcp-facture-electronique-fr    (France — XP Z12-013, Chorus Pro)
├── mcp-einvoicing-be              (Belgium — Peppol BIS 3.0, PINT-BE, Mercurius)
├── mcp-facturacion-electronica-es (Spain — this package)
│   ├── verifactu/   record generation, hash chain, QR, cancellation
│   ├── facturae/    Facturae 3.2.2 XML, XAdES-EPES, FACe submission
│   ├── sii/         batch building, AEAT SOAP, corrections
│   ├── ticketbai/   XML generation, provincial routing, validation
│   ├── b2b/         UBL/Facturae Crea y Crece, mandate detector
│   └── utils/       regime detection, AEAT response parser, deadline registry
├── mcp-fattura-elettronica-it     (Italy — FatturaPA / SDI)
└── mcp-ksef-pl                    (Poland — KSeF / FA(2))

供应商中立性

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

记录和发票会使用您自己的证书，直接发送至税务机关——AEAT（SII、VeriFactu）、FACe，或相关省级 TicketBAI 平台；过程中不涉及任何中间方。

支持的标准

西班牙电子发票生态系统包含六种并行系统，各自的适用范围、格式和时间安排均不相同。VERI*FACTU 引入防篡改的链式发票记录，并实时提交至 AEAT（Agencia Estatal de Administracion Tributaria）；根据 RD-ley 15/2025，自 2027 年起适用于大多数企业。SII 已对大型纳税人强制实施，信息须在 4 天内报送。带有 XAdES-EPES 签名的 Facturae XML 覆盖所有通过 FACe 门户办理的 B2G 发票。巴斯克地区独立实施 TicketBAI，三个省级主管机构分别维护自己的 XSD 架构和端点。纳瓦拉实行 NaTicket。《Ley Crea y Crece》要求所有企业采用 B2B 电子发票；RD 238/2026（BOE-A-2026-7295）确认了获准格式（EN 16931：CII/UBL/EDIFACT/Facturae），而制定公共解决方案技术方案的 Orden Ministerial 仍待发布。基于税务住所和营业额判定适用制度，是开展其他所有操作的前提：请先使用 es__detect_regional_regime。

法规覆盖情况

系统	适用范围	格式	强制实施时间	状态
*VERIFACTU**	所有非 SII 企业	专有 XML（XSD v1.0 HAC/1177/2024）	IS：2027 年 1 月 / 其他企业：2027 年 7 月（RD-ley 15/2025）	已实现（待法规确认）
Facturae / FACe	B2G（公共部门）	Facturae 3.2.2 + XAdES-EPES	自 2015 年起强制实施（Ley 25/2013）	已实现（待法规确认）
SII	营业额 > 600 万 EUR、增值税集团、REDEME	AEAT XML SOAP/REST	已强制实施（RD 596/2016）	已实现（待法规确认）
TicketBAI	Araba、Gipuzkoa、Bizkaia	省级 XML + XAdES + QR	按省份分阶段实施，2022-2023 年	已从范围中移除（v0.2.0）
Crea y Crece（B2B）	所有企业（Orden Ministerial 发布后 12/24 个月，视营业额而定）	UBL 2.1 或 Facturae 3.2.2（EN 16931）；也认可 CII/EDIFACT，但尚未实现	RD 238/2026 已发布；Orden Ministerial（公共解决方案）待发布	已实现（格式已由 RD 238/2026 确认；公共解决方案对接将推迟至 Orden Ministerial 发布后）
NaTicket	纳瓦拉	Foral XML + 签名	Foral 强制要求（分阶段实施）	部分实现（通过 `es__detect_regional_regime`）

SII / VERI*FACTU 互斥（Real Decreto 254/2025）： 已加入 SII 的纳税人可免于实施 VERI*FACTU。生成任何记录前，请使用 es__check_b2b_mandate_applicability。

合规说明

注意： 强制实施日期依据 RD-ley 15/2025（2025 年 12 月），可能因后续立法或 AEAT 行政指引而变更。本软件不构成法律或税务建议。

强制实施时间表

系统	适用对象	截止日期
SII	营业额 >6M EUR / VAT 集团 / REDEME	已强制实施（RD 596/2016）
Facturae/FACe	所有 B2G 供应商	已强制实施（Ley 25/2013）
TicketBAI	巴斯克地区所有企业	按行业分阶段实施，2022-2023 年
VERI*FACTU	IS（Impuesto sobre Sociedades）纳税人	2027 年 1 月（RD-ley 15/2025）
VERI*FACTU	IRPF + 其他非 SII 纳税人	2027 年 7 月（RD-ley 15/2025）
Crea y Crece B2B	营业额 >8M EUR（art. 121 Ley 37/1992）	Orden Ministerial 生效后 12 个月 `[Unverified date]`
Crea y Crece B2B	所有其他企业	Orden Ministerial 生效后 24 个月 `[Unverified date]`

地区例外

巴斯克地区： TicketBAI 取代 VERI*FACTU。三个省（Araba、Gipuzkoa、Bizkaia）的 XSD、端点和软件认证流程各不相同。国家 AEAT 端点不适用。
纳瓦拉： 适用 NaTicket（Hacienda Foral de Navarra）。VERI*FACTU 不适用。
休达 / 梅利利亚： 适用 IPSI（而非 VAT）；SII/VERI*FACTU 的适用情况不同，请向 AEAT 核实。
SII / VERI*FACTU 互斥： Real Decreto 254/2025 规定这两套系统互斥。已登记加入 SII 的纳税人无需提交 VERI*FACTU 记录。

所有 AEAT 提交端点均要求使用 FNMT-RCM 证书或认可认证机构颁发的证书。 AEAT 提供免费的测试环境：prewww2.aeat.es。

测试

# Install development dependencies
uv sync --all-extras

# Run the full test suite
uv run pytest tests/ -v

# With coverage report
uv run pytest --cov=mcp_facturacion_electronica_es --cov-report=term-missing

参与贡献

开始重要工作前，请先创建 issue。对于可在不同国家适配器间复用的工具逻辑，请先在 mcp-einvoicing-core 中创建 core-promotion issue，再进行实现：使用评分标准（3 = 必须推广，2 = 应当推广，1 = 保留在此处）。

git clone https://github.com/cmendezs/mcp-facturacion-electronica-es.git
cd mcp-facturacion-electronica-es
uv sync --all-extras
uv run pytest
make audit

所有法规相关陈述都必须引用具体的 BOE 发布文件、官方 XSD 版本或 AEAT 技术指南版本。除非在 PR 描述中附上经核实的来源链接，否则请勿移除 ⚠️ Pending regulatory confirmation。

其他电子发票 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 License 2.0 发布。完整版本历史请参阅 CHANGELOG.md。

支持 Markdown

登录后评论

基本信息

作者: cmendezs
语言: python
版本: 0.10.1
传输方式: stdio
收录时间: 2026年9月12日
最近更新: 7 周前
官方 Registry: io.github.cmendezs/mcp-facturacion-electronica-es

报告问题

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

mcp-facturacion-electronica-es

关于 mcp-facturacion-electronica-es

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

mcp-facturacion-electronica-es 🇪🇸

简介

安装

从 PyPI 安装（推荐）

从源代码安装

配置

AEAT / VERI*FACTU / SII

FACe

TicketBAI

通用（继承自 mcp-einvoicing-core）

Claude Desktop 集成

Cursor 集成

Kiro 集成

可用工具

VERI*FACTU

es__generate_verifactu_record

es__validate_verifactu_record

es__submit_verifactu_to_aeat

es__generate_qr_verifactu

es__cancel_verifactu_record

es__query_verifactu_status

Facturae / FACe

es__generate_facturae_xml

es__sign_facturae_xades

es__submit_to_face

es__get_face_invoice_status

es__validate_facturae_schema

SII（Suministro Inmediato de Informacion）

es__build_sii_invoice_record

es__submit_sii_batch

es__query_sii_status

es__generate_sii_correction

TicketBAI

es__generate_ticketbai_xml

es__submit_ticketbai

es__validate_ticketbai_schema

Crea y Crece / B2B

es__generate_b2b_einvoice_es

es__check_b2b_mandate_applicability

实用工具

es__detect_regional_regime

es__get_compliance_status

es__parse_aeat_response

架构

供应商中立性

支持的标准

法规覆盖情况

合规说明

测试

参与贡献

其他电子发票 MCP 服务

许可证

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？

我维护的项目已被收录，怎样认领？

通用（继承自 `mcp-einvoicing-core`）

`es__generate_verifactu_record`

`es__validate_verifactu_record`

`es__submit_verifactu_to_aeat`

`es__generate_qr_verifactu`

`es__cancel_verifactu_record`

`es__query_verifactu_status`

`es__generate_facturae_xml`

`es__sign_facturae_xades`

`es__submit_to_face`

`es__get_face_invoice_status`

`es__validate_facturae_schema`

`es__build_sii_invoice_record`

`es__submit_sii_batch`

`es__query_sii_status`

`es__generate_sii_correction`

`es__generate_ticketbai_xml`

`es__submit_ticketbai`

`es__validate_ticketbai_schema`

`es__generate_b2b_einvoice_es`

`es__check_b2b_mandate_applicability`

`es__detect_regional_regime`

`es__get_compliance_status`

`es__parse_aeat_response`