dutch-tax-income-calculator-mcp

A remote MCP server, deployed on Cloudflare Workers, that exposes the dutch-tax-income-calculator npm package as MCP tools and a resource. This server never reimplements Dutch tax logic or copies tax tables — every calculation is delegated directly to the package.

Indicative only — not tax advice. Every tool result includes this disclaimer. Confirm with a qualified Dutch tax advisor or the Belastingdienst before acting on any number this server returns.

What it exposes

Tools

• calculate_net_salary — gross → net, wraps the package's SalaryPaycheck class.

• calculate_gross_from_net — net → gross, wraps the package's netToGross solver. Because every internal amount is rounded to 2 decimals, more than one gross can round to the same net; when that happens the tool returns the package's own plateau bounds (grossLow / grossHigh) verbatim instead of guessing. If no gross produces the target net, the package's "no solution" error message is returned verbatim, unmodified.

• compare_scenarios — runs 2 to 5 calculate_net_salary-shaped scenarios side by side and returns a markdown comparison table alongside the per-scenario results.

Every tool result returns: normalizedInput, result, breakdown[] (payroll tax, social security, general credit, labour credit), assumptions[], and a permalink to the equivalent scenario on thetax.nl.

Resource

• tax://brackets/{year} — reads data.json from the package directly: payroll tax, social security, general credit and labour credit brackets, plus 30% ruling thresholds, for the requested year.

year is validated against the years actually present in the package's data.json on every tool call and resource read. An unsupported year always returns a clear, explicit error — never a silent fallback to the nearest year.

Related MCP server: irs-taxpayer-mcp

Stack

• MCP TypeScript SDK v2 (@modelcontextprotocol/server)

• createMcpHandler from agents/mcp/server (Cloudflare Agents SDK) as the entire Worker fetch handler — stateless, no Durable Objects, no McpAgent. createMcpHandler is given a factory function (createServer) that builds a fresh McpServer per request; no server or transport instance is ever held in module scope.

• Zod v4 for input validation

• Wrangler + Vitest (@cloudflare/vitest-pool-workers)

No Hono, no Express — src/index.ts is the whole HTTP layer.

Rate limiting & privacy

• 60 requests/minute per client IP, enforced via a Cloudflare Rate Limiting binding (wrangler.jsonc), on every request. Exceeding it returns 429 with a Retry-After header.

• Zero logging of input values. The handler never logs request bodies, tool arguments, or calculated amounts. The client IP is used only as an ephemeral rate-limit counter key, never stored or logged.

• Full policy at thetax.nl/privacy.

Development

npm install
npm run dev        # wrangler dev, http://localhost:8787/mcp
npm test           # vitest (unit tests + Worker-level MCP/HTTP integration tests)
npm run typecheck
npm run deploy      # wrangler deploy

Connecting a client

The server speaks the MCP Streamable HTTP transport at /mcp.

Claude Desktop

Claude Desktop connects to remote MCP servers through the mcp-remote bridge. Add this to claude_desktop_config.json:

{
  "mcpServers": {
    "dutch-tax-income-calculator": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://thetax.nl/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

mcp.json (VS Code, Cursor, and other clients supporting the standard config format)

{
  "servers": {
    "dutch-tax-income-calculator": {
      "type": "http",
      "url": "https://thetax.nl/mcp"
    }
  }
}

Claude Code

A real CLI command — run it directly in your terminal:

claude mcp add --transport http dutch-tax-income-calculator https://thetax.nl/mcp

Codex CLI

Codex's CLI only has a one-liner for local (stdio) servers; a remote HTTP server like this one needs a config.toml edit instead. Since Codex is itself an agent with file access, the easiest path is to paste this prompt into Codex chat and let it make the edit:

Add a remote MCP server to my Codex CLI config. Edit ~/.codex/config.toml (or ./.codex/config.toml for this project only) and add:

[mcp_servers.dutch-tax-income-calculator]
url = "https://thetax.nl/mcp"

No authentication is needed, so no bearer_token_env_var or http_headers are required. Then confirm the entry was added correctly.

Deployed at thetax.nl/mcp (path-scoped routes on the existing thetax.nl zone, not a custom domain — the rest of the site is unaffected). A human-readable documentation page with these same instructions, plus the full input/output schema for every tool, is served at thetax.nl/mcp/docs. If you deploy your own copy, replace the URL with the workers.dev subdomain npm run deploy assigns (or your own domain/route).

Project layout

src/
  index.ts          Worker fetch handler: per-IP rate limit + createMcpHandler(createServer)
  server.ts          createServer() factory — registers the 3 tools and the tax://brackets/{year} resource
  docs-page.ts        Renders the /mcp/docs page (setup instructions + full tool schemas)
  privacy-page.ts     Renders the /privacy policy
  terms-page.ts       Renders the /terms of service
  icon.ts             Base64-embedded PNG served at /mcp/icon.png
  env.ts             Env (RATE_LIMITER binding, OPENAI_APPS_CHALLENGE_TOKEN) type
  tax/
    schemas.ts        Zod v4 input schemas
    years.ts           Year validation against the package's constants.years
    paycheck.ts        Thin wrappers around SalaryPaycheck / netToGross — no tax logic here
    breakdown.ts       breakdown[] / assumptions[] builders
    permalink.ts       thetax.nl permalink builder
    compare.ts         Comparison table builder for compare_scenarios
test/                 Vitest unit tests + Worker-level MCP/HTTP integration tests

Routes

/docs, /mcp/setup(.html), /mcp/privacy.html, and /mcp/terms.html redirect to the routes above for continuity.