zatca-toolkit-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
zatca-toolkit
Generate, sign, validate and submit Saudi ZATCA (Fatoora) Phase 2 e-invoices in TypeScript, plus an MCP server so AI assistants can do it too.
Try it in your browser → Build, sign, validate and decode invoices client-side; nothing is uploaded.
Pure TypeScript: no OpenSSL, no Java, no temp files. Runs in Node, browsers and edge workers. MIT licensed.
ZATCA's Wave 25 brings every VAT-registered business with revenue above SAR 187,500 into Phase 2 integration by 1 February 2027. This library is for the developers wiring that up.
Why another ZATCA library?
Because ZATCA's byte-level rules are unforgiving, and most open-source implementations get some of them wrong. This one is verified, not hoped:
✅ Reproduces the invoice hash, signature, certificate digest, SignedProperties digest and every QR tag of all 19 official signed samples in ZATCA SDK 3.4.8, byte for byte.
✅ Re-signing each official sample yields ZATCA's own invoice hash.
✅ CSR is byte-identical (CertificationRequestInfo) to the sample CSR in ZATCA's official sandbox API spec.
✅ Passed the live ZATCA developer sandbox end to end (2026-11-10): compliance CSID → all 6 compliance documents (standard/simplified × invoice/credit/debit) PASS with zero warnings → production CSID → simplified invoice REPORTED → standard invoice CLEARED.
✅ 186 automated tests, including the W3C canonicalization test vectors.
Related MCP server: Kontor MCP
The traps it handles (that other libraries trip on)
Trap | What ZATCA actually does |
Invoice hash | C14N of the document with |
First PIH | The only base64-of-hex value (88 chars); every later PIH is base64 of raw bytes (44 chars). |
What gets signed | ECDSA secp256k1 over the 32 raw hash bytes, not a standard XMLDSig over |
Certificate digest |
|
SignedProperties digest | Hash of the element as indented in the document with |
QR lengths | ZATCA parses BER-TLV: values of 128+ bytes need the long form |
QR tag 4 |
|
Signature insertion | Must not add whitespace inside the hashed region; the signer re-hashes the final document and refuses to return a mismatch. |
CSR | VAT number in SAN |
Money | Exact decimal arithmetic, half-up rounding, VAT computed per category total (not a sum of rounded line VATs). |
Install
npm install zatca-toolkitQuick start
import { createSignedInvoice, validateInvoice, FatooraClient } from 'zatca-toolkit';
const signed = createSignedInvoice(
{
kind: 'simplified', // B2C; use 'standard' for B2B
number: 'INV-0001',
issueDate: '2026-11-10',
issueTime: '14:05:00',
counter: 1, // ICV: strictly increasing per device
// previousInvoiceHash: omit for the first invoice
seller: {
name: 'شركة المثال | Example Co',
vatNumber: '399999999900003',
identification: { scheme: 'CRN', value: '1010010000' },
address: { street: 'King Fahd Rd', buildingNumber: '1234', district: 'Al Olaya', city: 'Riyadh', postalCode: '12211', country: 'SA' },
},
lines: [{ name: 'Consulting hour', quantity: 2, unitPrice: '250.00', vat: { category: 'S' } }],
},
{ privateKey: process.env.ZATCA_PRIVATE_KEY!, certificate: process.env.ZATCA_CERTIFICATE! },
);
signed.xml; // signed UBL XML
signed.qr; // base64 QR payload, render it as the QR image
signed.invoiceHash; // store it: it is the next invoice's previousInvoiceHash
validateInvoice(signed.xml); // offline pre-check with English + Arabic messages
const zatca = new FatooraClient({ environment: 'sandbox' });
await zatca.reportInvoice({ binarySecurityToken, secret }, signed);Onboarding (getting a CSID)
import { generateKeyPair, generateCsr, egsSerialNumber, FatooraClient, SANDBOX_OTP } from 'zatca-toolkit';
const { privateKey } = generateKeyPair();
const csr = generateCsr({
commonName: 'EGS1-399999999900003',
serialNumber: egsSerialNumber('MyPOS', '1.0', 'device-123'),
vatNumber: '399999999900003',
organizationUnit: 'Riyadh Branch',
organizationName: 'Example Co',
invoiceType: '1100', // standard + simplified
location: 'RRRD2929',
industry: 'Retail',
environment: 'sandbox', // sandbox | simulation | production
}, privateKey);
const zatca = new FatooraClient({ environment: 'sandbox' });
const ccsid = await zatca.requestComplianceCsid(csr.apiValue, SANDBOX_OTP);
// sign one invoice, credit note and debit note per declared type with ccsid.binarySecurityToken,
// send each with zatca.checkCompliance(ccsid, doc), then:
const pcsid = await zatca.requestProductionCsid(ccsid, ccsid.requestID);scripts/sandbox-e2e.ts runs the whole flow against the live sandbox: npx tsx packages/core/scripts/sandbox-e2e.ts.
API overview
Function | Purpose |
| Unsigned UBL 2.1 XML (invoice, credit note, debit note) with computed totals |
| Hash, ECDSA, XAdES, QR; inserted without touching hashed bytes |
| Both of the above |
| Offline checks: common BR-KSA / EN 16931 rules, totals, hash, signature, digests, QR |
| Plain-language explanation (EN + AR) and fix for rule and API error codes |
| The value ZATCA expects in |
| BER-TLV QR payloads; |
| secp256k1 keys and ZATCA-shaped CSRs |
| Compliance CSID, compliance checks, production CSID, renewal, reporting, clearance |
| Exact VAT arithmetic |
The Fatoora API does not allow browser CORS, so call FatooraClient from a server.
Use it from Claude Code, Codex, Cursor and other agents
Claude Code plugin (skill + MCP server in one install):
/plugin install zatca-einvoicing --marketplace SalmanKhan957/zatca-toolkitOn older Claude Code versions: /plugin marketplace add SalmanKhan957/zatca-toolkit, then /plugin install zatca-einvoicing@zatca-toolkit.
Skill only, for any agent that supports Agent Skills (Codex, Cursor, Copilot, Gemini CLI):
npx skills add SalmanKhan957/zatca-toolkitThe skill teaches the agent when and how to use the toolkit: which flow fits B2C vs B2B, what to check before creating an invoice, onboarding steps, and fixes for common ZATCA errors.
MCP server (Claude, Cursor, any MCP client)
zatca-toolkit-mcp exposes the toolkit to AI assistants: create_invoice, validate_invoice, decode_qr, explain_error, compute_invoice_hash, generate_csr and submit_invoice.
{
"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>",
"ZATCA_CSID_SECRET": "<secret>",
"ZATCA_SELLER_FILE": "/path/to/seller.json"
}
}
}
}Then ask: "Create a simplified invoice for 2 hours of consulting at 250 SAR", "Why does ZATCA say BR-KSA-37?", or "Validate ./invoice.xml".
The ICV counter and previous-invoice hash are kept in
~/.zatca-toolkit/state.json(override withZATCA_STATE_FILE).Private keys are written to files and never printed.
Production submissions are refused unless
ZATCA_ALLOW_PRODUCTION=1.
Browser playground
packages/demo is the live playground: a single page that builds, signs, validates and decodes invoices entirely client-side (it shows the library running in a browser). It signs with a throwaway test certificate generated in the page.
npm run build -w zatca-toolkit-demo # -> packages/demo/dist/index.html (one self-contained file)
npx wrangler pages deploy packages/demo/dist --project-name zatca-toolkit # free Cloudflare Pages hostingRunning the tests
npm install
npm testThe conformance suite runs against ZATCA's official SDK samples when they are present. They are LGPL-licensed and not redistributed here; see reference-samples/SOURCES.md for where to download them. Without them, the remaining tests still run.
Scope and limitations
validateInvoicechecks the rules developers break most often. It is a pre-flight check, not ZATCA's validator: it does not run all 240+ schematron assertions or the XSD.Document-level charges, prepayment invoices (386) and non-SAR currencies with full prepayment handling are not built by
buildInvoiceXmlyet. Signing and validating such documents works.docs/zatca-spec-notes.mdrecords every byte-level decision with its source, and lists what is still unverified.
Disclaimer
Not affiliated with, endorsed by, or approved by ZATCA. Passing the sandbox or this library's checks does not mean ZATCA has approved your invoices; taxpayers remain responsible for compliance.
License
MIT
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Saudi ZATCA Fatoora Phase 2: AI agents report B2C and clear B2B tax invoices, stateless.
Validate, extract, repair and generate French Factur-X / EN16931 invoices via AgentForge API
Create ZUGFeRD e-invoices from JSON or PDF, verify Factur-X, check VAT IDs and Peppol.
Generate & validate EN 16931 e-invoices (Factur-X, ZUGFeRD, XRechnung); verification certificates
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to issue Poland structured e-invoices (faktura ustrukturyzowana) through KSeF 2.0, handling FA(3) XML building, encrypted session flow, and KSeF number retrieval.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to locally parse, validate, audit, explain, generate, and convert XRechnung and ZUGFeRD/Factur-X e-invoices using official rule sets, fully offline with no API keys required.Apache 2.0

rechnungsapi-mcpofficial
AlicenseAqualityBmaintenanceEnables AI assistants and agents to create, validate, read and convert German and EU e-invoices in ZUGFeRD, XRechnung and Factur-X formats, including extracting structured data from scanned or PDF invoices and embedding XML into PDF/A-3 files. It can run as a hosted remote server or locally, with each request authenticated by the caller's own API token.1024 npmMIT- AlicenseAqualityBmaintenanceEnables AI agents to audit Spanish VERI*FACTU invoice chains and exported XML by recomputing AEAT fingerprints and verifying record links, generate AEAT tax QR codes and images, and build or validate Facturae 3.2.2 invoices offline. It also exposes helpers for NIF checks, QR URL checks, compliance deadlines, and credit balances.11154 PyPIBusiness Source 1.1