ZATCA e-invoicing (Saudi Fatoora)

io.github.SalmanKhan957Published by GitHub account SalmanKhan957v0.1.1Updated Nov 14, 2026

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

VerifiedSTDIODesktop onlyFinanceDeveloper Tools

Overview

AI-generated overview

Creates, signs, validates and submits Saudi ZATCA Phase 2 e-invoices, decodes invoice QR codes and explains ZATCA errors.

What you can do
  • Build and sign UBL invoices, credit notes and debit notes with VAT totals, keeping the ICV/PIH chain
  • Validate invoice XML offline against BR-KSA/EN 16931 rules, totals, hash, signature, XAdES and QR tags
  • Decode ZATCA QR TLV payloads and flag non-BER lengths
  • Explain ZATCA rule codes and API error responses in English and Arabic
  • Compute the invoice hash for debugging or as the next PIH
  • Generate a secp256k1 key and CSR for onboarding an e-invoicing unit
When to use it
Useful when you work with Saudi e-invoicing: drafting and signing invoices, pre-checking XML before submission, debugging hash or QR problems, onboarding an e-invoicing unit, or filing simplified and standard invoices through the Fatoora API.
Requirements
Runs locally via npx (Node.js). All variables are optional; without credentials you can only validate, decode, explain and create unsigned invoices. Signing and submission need ZATCA_PRIVATE_KEY_FILE, ZATCA_CERTIFICATE, ZATCA_CSID_SECRET and ZATCA_SELLER_FILE. ZATCA_ENV selects sandbox (default), simulation or production; production submission also needs ZATCA_ALLOW_PRODUCTION set to 1. Network access is needed for submission.
Before you install
Handles tax credentials: a secp256k1 private key file, the CSID certificate and the CSID secret. Submitting to production creates real tax filings, so keep ZATCA_ENV on sandbox until ready and treat ZATCA_ALLOW_PRODUCTION as a deliberate switch. Signed invoices and credentials are sent to ZATCA's Fatoora API. The ICV/PIH state file is written locally and must stay consistent. Not affiliated with or endorsed by ZATCA.

Installation

In SourceWeft

  1. Open ZATCA e-invoicing (Saudi Fatoora) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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.

Source: packages/mcp/README.md at commit 8ab56cd

Tools

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.

ParameterskindrequirednotesigntypebuyerlinesrequirednumberrequiredreasonsellercounterissueDateissueTime+5 more

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.

Parametersxmlpath

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.

Parametersqrrequired

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.

Parameterserrorrequired

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.

Parametersxmlpath

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.

ParametersindustryrequiredlocationrequiredvatNumberrequiredcommonNamerequiredenvironmentinvoiceTyperequireddeviceSerialrequiredsolutionNamerequiredkeyOutputPathrequiredmodelOrVersionrequiredorganizationNamerequiredorganizationUnitrequired

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.

Parametersxmlmoderequiredpath

Version history

1
  1. v0.1.1LatestNov 14, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts