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"]
    }
  }
}

{
  "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"
      }
    }
  }
}

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: