Hilan MCP

hilan-mcp

An MCP server for [Hilan](https://net.hilan.co.il) (Hilanet / חילן, חילנט) — pull your payslips and Form 106 into any AI assistant, for any Hilan tenant.

There's no official Hilan API. hilan-mcp drives a real (headless) Chromium browser via Playwright to log in, then reuses that same authenticated session to call Hilan's internal endpoints and download PDFs — no fragile hand-rolled cookie replay, and no plaintext secrets stored anywhere.

Table of contents

• Features
• How it works
• Setup
• 0. If you're on npm 12 or newer
• 1. Register a tenant and enter credentials
• 2. Add the server to your MCP client config
• 3. Use it
• For AI agents setting this up on a user's behalf
• MCP tools
• Scope
• Reliability notes
• Security model
• Development
• License

Features

• 📄 Payslips — structured Bruto/Neto/salary-parts data, plus the PDF, for any month in the tenant's history.
• 🧾 Form 106 — annual tax summary PDFs, per year.
• 🔐 Encrypted local storage — SQLCipher-encrypted SQLite, key never written to disk in plaintext; OS-native credential store (Keychain/DPAPI/Secret Service) support.
• 🏢 Any Hilan tenant — login form fields are detected per-tenant instead of hardcoded to one employer.
• 💬 Answers, not raw JSON — tools like query answer "how much did I earn in June?" straight from local data, no network round-trip.
• 🔄 Self-updating awareness — the server checks for newer versions and lets your AI agent offer to update you, without needing its own UI.

How it works

This server drives a real (headless) Chromium browser via Playwright to log in, then reuses that same authenticated browser context's HTTP client (context.request) to call Hilan's internal .asmx JSON endpoints and download PDFs — so it automatically inherits whatever cookies/headers a real page load would have set up, instead of a fragile hand-rolled cookie replay.

Login form fields differ per Hilan tenant (some have 2 fields, some 3), so the login form is inspected fresh for each tenant the first time you ingest credentials, rather than hardcoded to one company.

Setup

0. If you're on npm 12 or newer

npm 12 blocks dependency install scripts unless you allow them, and one of this package's dependencies (better-sqlite3-multiple-ciphers, the encrypted SQLite engine) needs its install script to compile a native binding. Without it, setup appears to succeed and then every tool that touches the database fails. Allow it once, for all future npx and global installs:

npm config set allow-scripts=better-sqlite3-multiple-ciphers --location=user

Or per install, if you'd rather not set it globally:

npm install -g --allow-scripts=better-sqlite3-multiple-ciphers hilan-mcp

On npm 11 and older this isn't needed — install scripts still run by default. Check with npm --version.

1. Register a tenant and enter credentials

Run this yourself, directly in your own terminal — never paste real credentials into an AI chat. It installs the Chromium browser Playwright needs (one-time), launches a headless browser, detects your tenant's actual login fields, and prompts you for each one (passwords are masked). No local clone or npm install needed — npx fetches the package on the fly:

npx hilan-mcp setup --tenant amdocs        # tenant subdomain

or

npx hilan-mcp setup --tenant 5227 # numeric org code, resolved automatically

If you already have the package installed some other way, the equivalent

lower-level command is npx hilan-mcp ingest-creds --tenant <...> —

setup just also handles the one-time Chromium install first.

The first time you run this you'll be asked to set an encryption key for the local database (min 6 characters) — this key is never written to disk in plaintext.

For the MCP server to open the database on its own (without a human present to respond to a prompt every time), it looks for the key in this order:

1. OS credential store (recommended) — run npx hilan-mcp setup-key once, yourself, in your own terminal. You'll be asked to type a key (or press Enter to generate a strong random one), and it's stored in your OS's native secure storage: macOS Keychain (verified — same file that holds your Wi-Fi/browser passwords, silent, no dialogs), Windows (DPAPI, tied to your Windows user account), or Linux (Secret Service / secret-tool, needs a keyring daemon like GNOME Keyring or KWallet). Nothing ends up in any config file at all.
2. `HILAN_DB_KEY` env var — set it in the server's env block (see step 2). Same trust model as any other API key/secret configured for an MCP server in mcp.json (local file, not committed to git).
3. Desktop notification (last resort) — the server falls back to asking via a system notification (with a plain terminal prompt as a further fallback), but that requires a human to respond within ~30s of every tool call that needs the database, so it's not recommended for normal use.

2. Add the server to your MCP client config

Running the package with no arguments starts the MCP server itself (stdio transport) — that's what your MCP client's config actually invokes:

{

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

Single-employer setup — skip passing tenant on every tool call

If you only ever use this for one employer, you can set a default tenant in the server's env block. Only the first of these that's set is used, in this order — COMPANY_URL → COMPANY_TENANT → COMPANY_CODE:

{

"mcpServers": { "hilan": { "command": "npx", "args": ["-y", "hilan-mcp"], "env": { "COMPANY_TENANT": "amdocs", "HILAN_DB_KEY": "the-encryption-key-you-set-during-ingest-creds", "NODE_EXTRA_CA_CERTS": "/path/to/your-corporate-ca-bundle.pem" } } } }

HILAN_DB_KEY is only needed if you didn't run npx hilan-mcp setup-key (see step 1) — the OS credential store takes priority when both are present. NODE_EXTRA_CA_CERTS is only needed on networks with a TLS-intercepting corporate proxy (see Reliability notes) — omit it otherwise.

This same fallback also applies to npx hilan-mcp ingest-creds — --tenant is optional if one of these env vars is set. An explicit tenant argument (or --tenant flag) always overrides the env vars.

Running from a local clone instead of the published package

Use "command": "node", "args": ["/absolute/path/to/hilan-mcp/dist/cli/index.js"] (after npm install && npm run build in that clone) instead of the npx form above.

3. Use it

Ask your assistant things like "sync my last 3 payslips from Hilan", "download my Form 106 for 2025", or "how much net/gross did I earn in June 2026?" (answered instantly from the local database via the query tool, no network round-trip, once that month has been synced at least once) — see the full tool list below.

For AI agents (e.g. Claude) setting this up on a user's behalf

If a user asks you to set up hilan-mcp for them:

1. You must not run ingest-creds/setup/setup-key yourself via a shell tool — they prompt for a password and/or an encryption key interactively, and your shell tool's transcript could capture what the user types. Tell the user to open their own terminal and run npx hilan-mcp setup --tenant themselves, then (recommended) npx hilan-mcp setup-key. Check their npm --version first: on npm 12+ they also need step 0 or the database will fail to open later, in a way that doesn't look related to installation.
2. Once that's done, you can safely add the MCP server entry to the client's config file (the JSON blocks above) — that part has no secrets in it as long as the user used setup-key (OS credential store) rather than the HILAN_DB_KEY env var fallback.
3. After the config is added, the user (or their client) needs to reload/ restart the MCP connection for the new tools to appear.
4. Don't enable HILAN_ENABLE_DEBUG_TOOLS unless the user explicitly asks for the raw .asmx/PDF exploration tools — they're an intentional escape hatch (see Security model), not needed for normal use.
5. If a tool response includes an _updateNotice field, tell the user and ask if they'd like to update; if they decline, call dismissUpdateNotice with that version (see MCP tools).

MCP tools

Full tool reference (arguments, behavior, notes)

listTenants()

Configured tenants (subdomain, capability, whether login has succeeded before) — no secrets.

syncPayslips(tenant?, monthsBack?, skipPdf?)

Logs in (reusing a saved session if it still works), fetches structured Bruto/Neto/salary-parts data for the last N months (default 3), and downloads each payslip PDF. Set skipPdf: true for a much faster numbers-only sync (e.g. "what did I earn this year"). tenant is optional if COMPANY_URL/COMPANY_TENANT/COMPANY_CODE is set. The tenant's own archive length caps how far back this can actually go — no need to guess a start date.

resyncPayslipMonth(tenant?, period, skipPdf?)

Re-fetches one specific month (e.g. "10_2019" or "10/2019"), overwriting whatever's stored. Use this instead of re-running syncPayslips over the whole history just to retry one bad/truncated PDF or to answer a one-off "how much did I make in month X" question.

`syncForm106(tenant?