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 第二階段電子發票，解碼發票 QR 碼並解釋 ZATCA 錯誤。

可以做什麼
  • 產生並簽署 UBL 發票、貸項通知單與借項通知單，計算正確的營業稅合計並維護 ICV/PIH 鏈
  • 離線驗證發票 XML：BR-KSA/EN 16931 規則、合計、雜湊、簽章、XAdES 與 QR 各欄位
  • 解碼 ZATCA QR 的 TLV 資料，並標示 ZATCA 會拒絕的非 BER 長度
  • 以英文與阿拉伯文解釋 ZATCA 規則代碼與 API 錯誤回應
  • 計算發票雜湊，用於排查問題或作為下一個 PIH
  • 產生 secp256k1 私鑰與 CSR，用於電子開票單元註冊
適用情境
適合處理沙烏地電子開票的場合：草擬並簽署發票、提交前預檢 XML、排查雜湊或 QR 問題、註冊電子開票單元，或透過 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 分