hebrew-il-mcp

A Model Context Protocol server that gives AI agents reliable, deterministic tools for Israeli and Hebrew data — the things LLMs routinely get wrong when they try to do them "in their head":

Every tool returns both human-readable text and structuredContent, and invalid input produces an MCP isError result instead of crashing the session.

Why

Agents that handle Israeli invoices, CRM leads or bookkeeping keep tripping over the same things: an ID number that "looks fine" but fails the checksum, phone numbers stored in five formats, VAT computed at last year's rate, Hebrew dates hallucinated. These are pure, well-defined functions — so they belong in a tool, not in a prompt.

Related MCP server: Polymath MegaBlaster MCP

Usage

Claude Desktop / Cursor / any MCP client

{
  "mcpServers": {
    "hebrew-il": {
      "command": "npx",
      "args": ["-y", "github:Shtibel1/hebrew-il-mcp"]
    }
  }
}

Or from a local clone:

npm install && npm run build
node dist/cli.js   # speaks MCP over stdio

As a library

import { validateIsraeliId, calculateVat, toHebrewDate } from "hebrew-il-mcp";

validateIsraeliId("515555555", "corporate"); // { valid, normalized, kind: "company", ... }
calculateVat(1180, true, "2026-03-01");      // { rate: 0.18, net: 1000, vat: 180, gross: 1180 }
toHebrewDate("2026-11-01").formatted;        // "כ״א בחשוון תשפ״ז"

Design

src/
  lib/        pure, dependency-free domain functions (id, phone, vat, hebrew)
  server.ts   MCP wiring: zod input schemas + uniform JSON / isError results
  cli.ts      stdio transport entry point
test/
  lib.test.ts     unit tests for each domain module
  server.test.ts  end-to-end tests through a real MCP client (in-memory transport)

• Pure core, thin adapter. All logic lives in src/lib with no MCP dependency, so it is reusable as a plain TypeScript library and trivially testable.

• Date-aware VAT. Rates are a dated table, not a constant, so historical invoices are computed correctly.

• Hebrew calendar via ICU. Conversion uses Intl.DateTimeFormat with ca-hebrew (no hand-rolled calendar math); only the letter-numeral formatting is custom.

Development

npm test          # vitest
npm run typecheck
npm run build

License

MIT