arabic-invoice-mcp — Arabic e-invoicing tools for AI assistants

An MCP server that lets an AI assistant build a Saudi (ZATCA) tax invoice — six tools covering VAT totals, Arabic amount-in-words, and a Phase-1 TLV QR code built from the specification text.

Point Claude Desktop (or any MCP client) at it — no clone, no build:

{
  "mcpServers": {
    "arabic-invoice": {
      "command": "npx",
      "args": ["-y", "arabic-invoice-mcp"]
    }
  }
}

Or install it as a command:

npm i -g arabic-invoice-mcp
arabic-invoice-mcp          # stdio transport

What it gets right that most implementations do not: the TLV length is a BER length in bytes, not characters. شركة is 4 characters and 8 bytes, and past 128 bytes the single-byte form is invalid. We measured 11 packages carrying 44,915 npm downloads — 91.7% of those downloads encode it wrong. The benchmark is open.

Built on TypeScript 5.8 (ESM), Zod-validated inputs, MCP SDK 1.29+. 47 tests.

Not here: Phase-2 tags 6–9 (XML hash, ECDSA signature, certificates), and any claim about whether ZATCA accepted an invoice — that lives in the platform's response, not in the file.

Details below in Arabic. MIT.

نسخة TypeScript من Arabic Invoice MCP — 6 tools أساسية + ZATCA QR.

TypeScript port of arabic-invoice-mcp (Python) — 6 core tools compatible with the Python version.

✨ المميزات

• ✅ 6 MCP tools (نفس الـ Python API)
• ✅ ZATCA QR generator (TLV + Base64)
• ✅ TypeScript 5.8+ (ESM)
• ✅ Zod validation للـ inputs
• ✅ Strict mode + full type safety
• ✅ MCP SDK 1.29+ (stable v1)

🚀 التثبيت

npm i -g arabic-invoice-mcp   # ثم: arabic-invoice-mcp

أو بلا تثبيت: npx -y arabic-invoice-mcp. وللبناء من المصدر: npm install && npm run build && npm start.

🔗 إعداد Claude Desktop

{
  "mcpServers": {
    "arabic-invoice": {
      "command": "npx",
      "args": ["-y", "arabic-invoice-mcp"]
    }
  }
}

🛠️ الأدوات

| Tool | Description | |---|---| | tafgeet_amount | تفقيط مبلغ مالي | | convert_number_to_arabic | تحويل رقم إلى كلمات | | calculate_vat | حساب VAT حسب الدولة | | list_supported_currencies | العملات المدعومة | | list_supported_vat_rates | معدلات VAT | | generate_zatca_qr | QR code متوافق مع ZATCA |

🧪 الاختبارات

npm test

📊 Parity with Python

| Feature | Python | TypeScript | |---|---|---| | Tafgeet engine | ✅ | ✅ | | 5 currencies | ✅ | ✅ | | 7 VAT countries | ✅ | ✅ | | ZATCA QR (TLV) | ✅ | ✅ | | Invoice creation | ✅ | 🔜 | | Format invoice | ✅ | 🔜 | | Date converter | ✅ | 🔜 | | Saudi VAT Pro | ✅ | 🔜 |

🏗️ Architecture

arabic-invoice-mcp-ts/
├── src/
│   └── index.ts          # All tools + server
├── tests/
│   └── basic.test.ts     # Vitest
├── package.json
├── tsconfig.json
└── dist/                 # Build output

📝 License

MIT — نفس الـ Python version.