ZATCA e-invoicing (Saudi Fatoora)

io.github.SalmanKhan957由 GitHub 账号 SalmanKhan957 发布v0.1.1更新于 Nov 14, 2026

Create, sign, validate and submit Saudi ZATCA Phase 2 e-invoices; decode QR codes; explain errors.

已验证STDIO仅桌面金融开发者工具

概览

AI 生成的概览

创建、签署、校验并提交沙特 ZATCA 第二阶段电子发票，解码发票二维码并解释 ZATCA 报错。

可以做什么
  • 生成并签署 UBL 发票、贷项通知单和借项通知单，计算准确的增值税合计并维护 ICV/PIH 链
  • 离线校验发票 XML：BR-KSA/EN 16931 规则、合计、哈希、签名、XAdES 与二维码各字段
  • 解码 ZATCA 二维码 TLV 数据，并标记 ZATCA 拒绝的非 BER 长度
  • 用英文和阿拉伯文解释 ZATCA 规则代码与 API 错误响应
  • 计算发票哈希，用于排查问题或作为下一个 PIH
  • 生成 secp256k1 私钥与 CSR，用于电子开票单元注册
适用场景
适用于处理沙特电子开票的场景：起草并签署发票、提交前预检 XML、排查哈希或二维码问题、注册电子开票单元，或通过 Fatoora API 提交简化发票与标准发票。
运行要求
通过 npx 在本地运行（需要 Node.js）。所有变量均为可选；没有凭据时只能校验、解码、解释错误和创建未签名发票。签名与提交需要 ZATCA_PRIVATE_KEY_FILE、ZATCA_CERTIFICATE、ZATCA_CSID_SECRET 和 ZATCA_SELLER_FILE。ZATCA_ENV 选择 sandbox（默认）、simulation 或 production；提交到生产环境还需将 ZATCA_ALLOW_PRODUCTION 设为 1。提交需要网络访问。
安装前请注意
涉及税务凭据：secp256k1 私钥文件、CSID 证书和 CSID 密钥。提交到生产环境属于真实税务申报，准备好之前请保持 ZATCA_ENV 为 sandbox，并把 ZATCA_ALLOW_PRODUCTION 当作有意的开关。已签名发票和凭据会发送到 ZATCA 的 Fatoora API。ICV/PIH 状态文件写入本地，需保持一致性。与 ZATCA 无隶属或背书关系。

安装

在 SourceWeft 中

  1. 打开 控制台中的 ZATCA e-invoicing (Saudi Fatoora)，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only，通过 STDIO。 STDIO 服务会启动本地进程，因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

zatca-toolkit-mcp

An MCP server that lets Claude, Cursor or any MCP client create, sign, validate and explain Saudi ZATCA (Fatoora) e-invoices.

It is built on zatca-toolkit, whose output matches ZATCA's official SDK samples byte for byte and passed the live ZATCA sandbox end to end.

Tools

ToolWhat it does
create_invoiceBuild (and sign, if credentials are set) an invoice, credit note or debit note with exact VAT totals; keeps the ICV/PIH chain for you
validate_invoiceOffline pre-check: common BR-KSA / EN 16931 rules, totals, hash, signature, XAdES digests, every QR tag; English + Arabic explanations
decode_qrDecode a QR payload; flags non-BER lengths ZATCA rejects
explain_errorPaste a ZATCA error code or API response and get the cause and fix
compute_invoice_hashDebug invalid-invoice-hash
generate_csrNew secp256k1 key (saved to a file, never shown) + ZATCA CSR
submit_invoiceReport, clear or run compliance checks via the Fatoora API (sandbox by default)

Setup

json
{  "mcpServers": {    "zatca": {      "command": "npx",      "args": ["-y", "zatca-toolkit-mcp"],      "env": {        "ZATCA_ENV": "sandbox",        "ZATCA_PRIVATE_KEY_FILE": "/path/to/egs-key.pem",        "ZATCA_CERTIFICATE": "<binarySecurityToken from ZATCA>",        "ZATCA_CSID_SECRET": "<secret from ZATCA>",        "ZATCA_SELLER_FILE": "/path/to/seller.json"      }    }  }}

All variables are optional. Without credentials you can still validate, decode, explain and create unsigned invoices.

VariableMeaning
ZATCA_ENVsandbox (default), simulation or production
ZATCA_PRIVATE_KEY / _FILEsecp256k1 key (PEM or base64)
ZATCA_CERTIFICATE / _FILECSID certificate or the binarySecurityToken
ZATCA_CSID_SECRET / _FILECSID secret, needed to submit
ZATCA_SELLER / _FILESeller JSON: { name, vatNumber, identification: { scheme, value }, address: {...} }
ZATCA_STATE_FILEWhere the ICV counter and last hash are kept (default ~/.zatca-toolkit/state.json)
ZATCA_ALLOW_PRODUCTIONMust be 1 to submit to production

Not affiliated with or endorsed by ZATCA. MIT licensed.

来源：packages/mcp/README.md，提交 8ab56cd

工具

7

create_invoice

Create a ZATCA e-invoice

Build a ZATCA Phase 2 UBL invoice, credit note or debit note with exact VAT totals, and sign it (hash, ECDSA signature, XAdES, QR) when signing credentials are configured. Keeps the invoice counter (ICV) and previous-invoice-hash (PIH) chain in a local state file unless you pass them explicitly.

输入参数kind必填notesigntypebuyerlines必填number必填reasonsellercounterissueDateissueTime另有 5 个

validate_invoice

Validate a ZATCA e-invoice

Check a ZATCA XML invoice offline: common BR-KSA/EN16931 rules, totals arithmetic, and for signed documents the invoice hash, ECDSA signature, XAdES digests and every QR tag. Explains each problem in English and Arabic with a fix.

输入参数xmlpath

decode_qr

Decode a ZATCA QR code

Decode the base64 TLV payload of a ZATCA e-invoice QR code into its fields (seller, VAT number, timestamp, totals, hash, signature, key). Flags non-BER lengths that ZATCA rejects.

输入参数qr必填

explain_error

Explain a ZATCA error

Explain ZATCA rule codes or API error messages (e.g. "BR-KSA-37", "invalid-invoice-hash", or a pasted API response) in plain English and Arabic, with the fix.

输入参数error必填

compute_invoice_hash

Compute a ZATCA invoice hash

Compute the ZATCA invoice hash (base64 SHA-256 of the canonicalized XML without UBLExtensions, Signature and QR). Use it to debug "invalid-invoice-hash" or as the next PIH.

输入参数xmlpath

generate_csr

Generate a ZATCA key pair and CSR

Create a secp256k1 private key (written to a file, never shown) and the CSR needed to onboard an e-invoicing unit (EGS) with ZATCA. Returns the CSR and the exact value to send to POST /compliance.

输入参数industry必填location必填vatNumber必填commonName必填environmentinvoiceType必填deviceSerial必填solutionName必填keyOutputPath必填modelOrVersion必填organizationName必填organizationUnit必填

submit_invoice

Submit an invoice to ZATCA

Send a signed invoice to ZATCA's Fatoora API using the configured CSID: "report" (simplified/B2C), "clear" (standard/B2B, returns the stamped invoice) or "compliance" (onboarding checks). Uses ZATCA_ENV (sandbox by default). Production submissions are real tax filings and require ZATCA_ALLOW_PRODUCTION=1.

输入参数xmlmode必填path

版本历史

1
  1. v0.1.1最新Nov 14, 2026

评分

已满足适用检查项的 90%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分
  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分