Zatca MCP

🇸🇦 ZATCA MCP

AI原生沙特电子发票——从自然语言生成符合ZATCA的发票。

     

"Generate an invoice for 10 hours of consulting at 500 SAR to Al-Rajhi Corp" &rarr; compliant XML + QR code in seconds

______________________________________________________________________

为什么选择ZATCA MCP？

沙特阿拉伯的ZATCA授权要求 所有业务 发布结构化电子发票——自2021年12月以来的第一阶段（生成），第二阶段（集成）将在2025年之前在纳税人中推广。这是一个基石 2030年愿景 数字化转型。

问题： ZATCA电子发票没有开源的人工智能原生工具。企业要么为专有的ERP插件付费，要么从头开始构建合规性。

本项目： 沙特电子发票的第一个开源MCP服务器——让克劳德等人工智能代理通过自然对话生成、验证和管理符合ZATCA的发票。

特性

• 9 MCP工具 --生成、签署、验证、提交发票+二维码、CSR、合规性检查、HTML渲染
• 3 MCP资源 --验证规则、发票类型、用于AI参考的示例发票
• 3个MCP提示 --创建发票、验证和贷记/借记单的指导工作流程
• UBL 2.1 XML --根据OASIS标准生成完全符合命名空间的发票
• 16规则验证引擎 --BR-01至BR-16业务规则检查
• XAdES BES数字签名 --嵌入证书的ECDSA secp256k1签名
• ZATCA API集成 --用于合规性、报告和清除端点的异步客户端
• 贷记/借记票据 --类型代码381/383，带计费参考和说明注释
• TLV QR编码 --第1阶段+第2阶段标签支持（标签1-8，加密数据）
• Fikra命令行界面 --Claude Code风格的会话代理，带有HTML发票输出
• 127测试 -单元、集成、签名、API客户端、资源/提示和边缘库覆盖
• CI/CD管道 --ruff+mypy+pytest跨Python 3.10/3.11/3.12+第二阶段作业
• 阿拉伯语支持 --卖方/买方姓名和地址的完整UTF-8处理
• 小数精度 — Decimal 随着 ROUND_HALF_UP 适用于所有金融数学
• 多税率增值税 --每行项目增值税税率（默认15%）

建筑

graph TD
    subgraph Clients
        A[Claude Desktop]
        B[Claude Code]
        C[Fikra CLI]
    end

    subgraph MCP Server
        D[generate_invoice]
        E[generate_qr_code]
        F[validate_invoice]
        G[decode_qr]
        D2[generate_csr]
        D3[sign_invoice]
        D4[submit_invoice]
        D5[check_compliance]
    end

    subgraph Processing Engine
        H[XML Builder
UBL 2.1]
        I[Validation Engine
16 Business Rules]
        J[TLV Encoder
QR Phase 1 + 2]
        S[Signing Engine
XAdES-BES]
        API[ZATCA API Client
httpx async]
    end

    A -- MCP Protocol --> D
    B -- MCP Protocol --> E
    A -- MCP Protocol --> F
    B -- MCP Protocol --> G

    C -- Direct Call --> H
    C -- Direct Call --> I
    C -- Direct Call --> J
    C -. HTML Pipeline .-> K[Browser Invoice
with QR Image]

    D --> H
    D --> J
    E --> J
    F --> I
    G --> J
    D2 --> S
    D3 --> S
    D4 --> API
    D5 --> API

快速开始

安装

pip install zatca-mcp              # Phase 1 (generation + validation)
pip install zatca-mcp[phase2]      # Phase 2 (signing + ZATCA API)

与Claude Desktop一起使用

添加 ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zatca": {
      "command": "zatca-mcp"
    }
  }
}

重新启动克劳德桌面。现在，您可以要求Claude生成符合ZATCA标准的发票。

Fikra命令行界面

export ANTHROPIC_API_KEY="sk-ant-..."
pip install zatca-mcp[phase2]
fikra                              # works from any directory

Fikra命令行界面

一个Claude Code风格的会话代理，将自然语言转换为具有专业HTML输出的兼容发票。

特征：

• 渐变ASCII横幅 #c8e64a 品牌主题化
• ❯ 流式响应提示
• ⏺ 工具使用指示器（反映Claude Code UX）
• 自动生成内嵌二维码图像的HTML发票
• 在浏览器中自动打开发票
• 令牌使用情况显示(↳ input · output tokens)
• /help /clear /quit 命令

     ◇
    ◇◆◇
     ◇       ███████╗██╗██╗  ██╗██████╗  █████╗ ██╗  ██╗
    ╱ ╲      ██╔════╝██║██║ ██╔╝██╔══██╗██╔══██╗██║  ██║
   ╱   ╲     █████╗  ██║█████╔╝ ██████╔╝███████║███████║
   ╰───╯     ██╔══╝  ██║██╔═██╗ ██╔══██╗██╔══██║██╔══██║
              ██║     ██║██║  ██╗██║  ██║██║  ██║██║  ██║
              ╚═╝     ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═╝

  Model: claude-sonnet-4-20250514  |  Tools: 8 ZATCA tools  |  Phase 2 ✓  |  cwd: ~/zatca-mcp

  Tips: "I sold 10 laptops at 3000 SAR each to TechCo" to get started
        /help for commands, /quit to exit

❯ I just closed a deal with Al-Rajhi Corp for consulting — 10 hours at 500 SAR

  ⏺ generate_invoice

  ✓ Invoice saved & opened in browser
  ~/zatca-mcp/examples/invoices/INV-2026-001_20260217.html

  Great news on closing the deal! I've generated a ZATCA-compliant invoice
  for Al-Rajhi Corp — 10 hours of consulting at 500 SAR each.

  **Invoice Summary:**
  - Subtotal: 5,000.00 SAR
  - VAT (15%): 750.00 SAR
  - **Total: 5,750.00 SAR**

  The HTML invoice with embedded QR code is open in your browser.

  ↳ 1,847 input · 312 output tokens

工具API参考

generate_invoice — Create a ZATCA-compliant UBL 2.1 XML e-invoice

根据沙特阿拉伯的ZATCA电子发票标准创建完整的XML发票。支持标准（B2B）、简化（B2C）、贷记单和借记单类型。自动计算增值税、行总计，并嵌入二维码数据。

退货： 填写内嵌二维码的UBL 2.1 XML发票字符串。

generate_qr_code — Generate a TLV-encoded QR code

根据ZATCA的标签长度值（TLV）格式创建Base64编码的QR码有效载荷，以符合第1阶段和第2阶段的要求。

退货： JSON格式 qr_base64 和 decoded_verification 数据。

validate_invoice — Check invoice XML against ZATCA business rules

运行16个业务规则检查，包括必填字段、增值税编号格式、行总计和增值税计算的数学准确性、贷记/借记单引用以及UBL 2.1 XML的结构完整性。

退货： JSON格式 is_valid （布尔值）， errors （列表）， warnings （列表），以及 checks_run (16).

generate_csr — Generate a ZATCA-compliant Certificate Signing Request

生成ECDSA secp256k1密钥对和带有ZATCA必需主题字段的CSR。需要 cryptography （安装时 pip install zatca-mcp[phase2]).

退货： JSON格式 csr_pem, private_key_pem, warning，以及 next_step.

sign_invoice — Digitally sign an invoice with XAdES-BES

将XAdES BES数字签名注入到UBL 2.1发票XML中。使用第2阶段加密标签重建二维码（6-8）。需要 cryptography.

退货： JSON格式 signed_xml, invoice_hash, qr_base64，以及 is_phase2_compliant.

submit_invoice — Submit a signed invoice to the ZATCA API

向ZATCA Fatoora API提交签署的发票，用于报告（简化）或清关（标准）。需要 httpx 和 pydantic.

退货： ZATCA API响应 status, validationResults, warnings，以及 errors.

check_compliance — Check invoice compliance with ZATCA servers

向ZATCA合规性端点提交发票以进行服务器端验证。需要 httpx 和 pydantic.

退货： ZATCA合规性验证结果。

decode_qr — Decode a ZATCA TLV-encoded QR code string

从现有的ZATCA二维码中提取所有编码的标签值，以进行验证或检查。

退货： 带有解码标签名及其值的JSON。

程序化使用

from zatca_mcp.utils.xml_builder import build_invoice_xml
from zatca_mcp.utils.tlv import encode_tlv
from zatca_mcp.utils.validation import validate_invoice_xml

# Generate invoice
xml = build_invoice_xml(
    invoice_type="simplified",
    invoice_number="INV-2024-001",
    issue_date="2024-01-15",
    seller_name="Fikrah Tech",
    seller_vat="300000000000003",
    seller_address="123 King Fahd Road",
    seller_city="Riyadh",
    buyer_name="Walk-in Customer",
    line_items=[
        {"name": "AI Consulting", "quantity": 10, "unit_price": 500.00},
        {"name": "Setup Fee", "quantity": 1, "unit_price": 1000.00},
    ],
)

# Validate
result = validate_invoice_xml(xml)
print(f"Valid: {result['is_valid']}")  # True
print(f"Checks: {result['checks_run']}")  # 16

# Generate QR code
qr = encode_tlv(
    seller_name="Fikrah Tech",
    vat_number="300000000000003",
    timestamp="2024-01-15T10:00:00Z",
    total_amount="6900.00",
    vat_amount="900.00",
)
print(f"QR: {qr}")

第二阶段：数字签名

from zatca_mcp.utils.signing import (
    generate_private_key,
    generate_csr,
    inject_signature,
    hash_invoice,
)

# Generate key pair and CSR
key = generate_private_key()
csr_pem = generate_csr(
    key,
    common_name="My Company",
    organization="My Org",
    organizational_unit="IT",
)
# Submit CSR to ZATCA to get a certificate, then sign:
# signed_xml = inject_signature(xml, cert_pem, key)
# invoice_hash = hash_invoice(xml)

ZATCA合规性

验证规则（16条业务规则）

发票类型

二维码TLV标签

标签6-8由以下内容填充 sign_invoice 该工具具有真实的加密数据（SHA-256哈希、ECDSA签名、公钥）。

工程质量

• 127测试 跨越7个测试模块（TLV、验证、发票、签名、贷记/借记、API客户端、资源/提示）
• CI/CD --GitHub操作：ruff-lint+格式检查、mypy类型检查、覆盖Python 3.10/3.11/3.12的pytest，以及一个专门的第2阶段作业
• 小数精度 --所有财务计算均使用 Decimal 随着 ROUND_HALF_UP，从不浮点
• UBL 2.1合规性 --完整的OASIS命名空间声明(ubl, cac, cbc, ext, ds, xades)
• 阿拉伯语/UTF-8 — ensure_ascii=False 自始至终；阿拉伯卖方/买方名称正确
• 优雅降级 --如果出现以下情况，第2阶段工具将返回有用的错误 cryptography/httpx 未安装

项目结构

zatca-mcp/
├── src/zatca_mcp/
│   ├── server.py              # MCP server — 9 tools, 3 resources, 3 prompts
│   ├── cli.py                 # Fikra CLI — global `fikra` command
│   ├── utils/
│   │   ├── xml_builder.py     # UBL 2.1 XML invoice generator
│   │   ├── validation.py      # 16-rule validation engine
│   │   ├── tlv.py             # TLV QR encoder/decoder
│   │   └── signing.py         # XAdES-BES digital signing (Phase 2)
│   └── api/
│       ├── __init__.py
│       ├── client.py          # ZATCA Fatoora API client (Phase 2)
│       └── models.py          # Pydantic v2 API models (Phase 2)
├── examples/
│   └── fikrah_agent.py        # Legacy entry point (redirects to fikra command)
├── tests/
│   ├── test_invoice.py        # Invoice generation tests
│   ├── test_tlv.py            # TLV encoding/decoding tests
│   ├── test_validation.py     # Validation engine tests
│   ├── test_resources_prompts.py # MCP resources & prompts tests
│   ├── test_signing.py        # Digital signing tests (Phase 2)
│   ├── test_credit_debit.py   # Credit/debit note tests (Phase 2)
│   └── test_api_client.py     # API client tests (Phase 2)
├── .github/workflows/
│   └── test.yml               # CI pipeline (Phase 1 + Phase 2 jobs)
├── pyproject.toml
└── LICENSE

发展

git clone https://github.com/DoubleH10/zatca-mcp.git
cd zatca-mcp

# Phase 1 only
pip install -e ".[dev]"

# Phase 1 + Phase 2 (signing, API)
pip install -e ".[dev,phase2]"

# Tests
pytest tests/ -v                                    # All tests
pytest tests/ -v -m "not sandbox"                   # Skip live sandbox tests

# Linting & types
ruff check src/ tests/
mypy src/zatca_mcp/ --ignore-missing-imports

# MCP Inspector (interactive testing)
mcp dev src/zatca_mcp/server.py

路线图

• \[x\] TLV二维码生成（第1阶段+第2阶段标签）
• \[x\] UBL 2.1 XML发票生成
• \[x\] 16规则验证引擎（BR-01至BR-16）
• \[x\] 配备8个工具的MCP服务器
• \[x\] Fikra CLI（流媒体、HTML发票、QR图像）
• \[x\] CI/CD管道（ruff+mypy+pytest矩阵+第2阶段作业）
• \[x\] XAdES BES数字签名（ECDSA secp256k1）
• \[x\] ZATCA API集成（沙箱+生产）
• \[x\] 证书管理（CSR生成）
• \[x\] 贷记/借记单支持（381/383）
• \[\]PyPI包发布
• \[x\] MCP资源和提示
• \[\]HTTP/SSE传输
• \[\]阿拉伯RTL发票模板

使用zatca-mcp构建

在你的项目中使用zatca-mcp？打开一个PR添加到这里。

贡献

许可证

Apache 2.0——请参阅 许可证