hebrew-il-mcp

Deterministic Israeli & Hebrew tools for AI agents — ת״ז, IBAN, מע״מ, מיקוד, bank days, Hebrew dates, gematria.

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":

Tools

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

Related MCP server: mquickcalc-utility

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.

Quick start

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

Over HTTP (Streamable HTTP, stateless)

Run it as a hosted endpoint for remote agents, or behind a load balancer — every request gets a fresh server, so there are no sessions to pin:

node dist/cli.js --http --port 3000                      # POST http://127.0.0.1:3000/mcp, GET /healthz
node dist/cli.js --http --host 0.0.0.0 --allowed-origin https://app.example

PORT, HOST and ALLOWED_ORIGINS (comma-separated) are read when the flags are omitted. It binds to 127.0.0.1 by default, rejects browser requests from origins not on the allow-list (DNS-rebinding protection), and caps request bodies at 1 MB. Point any Streamable HTTP MCP client at /mcp.

As a library

import { validateIsraeliId, calculateVat, toHebrewDate, buildIsraeliIban, israeliBusinessDay, normalizeIsraeliPostalCode, lookupIsraeliCity } 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;        // "כ״א בחשוון תשפ״ז"
buildIsraeliIban(10, 800, 99999999);         // "IL620108000000099999999"
israeliBusinessDay("2026-04-22").businessDay; // false — Independence Day
normalizeIsraeliPostalCode("12-345-67");     // { valid: true, formatted: "12-345-67", ... }
lookupIsraeliCity("Hadera");                 // { found: true, he: "חדרה", ... }

Architecture

flowchart LR
  C["MCP client<br/>(Claude Desktop, Cursor, agents)"] -- stdio --> CLI[cli.ts]
  R["Remote agent"] -- "Streamable HTTP /mcp" --> HTTP["http.ts<br/>stateless · origin guard"]
  CLI --> S
  HTTP --> S["server.ts<br/>zod schemas · isError results"]
  S --> L
  subgraph L["src/lib — pure domain core"]
    ID[id] --- PH[phone] --- VAT[vat] --- IB[iban] --- PL[plate] --- PO[postal] --- HE[hebrew] --- HO[holidays]
  end
  APP["Your TS app"] -- import --> L

Layout

src/
  lib/        pure, dependency-free domain functions (id, phone, vat, iban, plate, postal, hebrew, holidays)
  server.ts   MCP wiring: zod input schemas + uniform JSON / isError results
  http.ts     stateless Streamable HTTP transport (/mcp, /healthz, origin guard, body cap)
  cli.ts      entry point: stdio by default, --http for the HTTP transport
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)
  http.test.ts    end-to-end tests through a real MCP client over HTTP

• 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.

• Curated postal / city table. ~70 major localities with prefix ranges — honest approximation, not a national Israel Post dump.

Development

npm test          # vitest
npm run typecheck
npm run build

Roadmap

• Publish to npm so npx hebrew-il-mcp works without the GitHub shorthand

• Israeli bank-holiday / business-day calendar tool

• Postal code and city-name normalization

• Hosted (Streamable HTTP) transport option

Contributing

Issues and PRs are welcome. Every tool should stay a pure function in src/lib with unit tests, plus an end-to-end case in test/server.test.ts.

License

MIT © Nadav Shtibel