Luzern eTax MCP

Luzern eTax MCP

An MCP server that lets AI agents explore and fill out Kanton Luzern tax declarations on the eSteuern.LU platform (Ringler eTax).

⚠️ Unofficial experiment. This is a personal, experimental project. It is not an official product and is not affiliated with, endorsed by, or supported by Kanton Luzern, Ringler Informatik AG, or eSteuern.LU. Use it at your own risk.

It exposes two things over the Model Context Protocol:

• An offline field catalogue — search and inspect every field in the Luzern declaration (German labels, IDs, printed-form positions) with no credentials and no network access.
• Live declaration tools — log in, create or open a declaration, read and write fields, save, and generate a review PDF against the training or production environment.

Quick start

npm install
npm test        # run the test suite
npm start       # start the MCP server

The server listens on http://127.0.0.1:3000/mcp using the MCP streamable HTTP transport. Override the bind address with the HOST and PORT environment variables.

Connect an agent

Point any MCP client at the running server. For example, in an MCP client config:

{
  "mcpServers": {
    "luzern-etax": {
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

The offline catalogue tools work immediately. The live tools need credentials (see Configuration) and an explicit environment argument — training or production — on every call.

Tools

Offline catalogue — no credentials, no network

| Tool | Purpose | | --- | --- | | search_fields | Search the field catalogue by keyword | | get_field | Look up a single field by its ID |

These read from config/model.xml, config/entity-labels.properties, and config/scantax.xml. Duplicate label keys are surfaced as catalogue diagnostics rather than silently dropped.

Live declaration — eSteuern.LU

| Tool | Purpose | | --- | --- | | list_declarations | List declarations visible to the configured login | | create_declaration | Create a declaration using the configured declaration credentials | | load_declaration | Open a declaration (normally automatic; useful for diagnostics) | | get_scope | Read a runtime scope of field values | | set_field | Update one field after catalogue and scope checks | | insert_list_entry | Insert a list entry after checking the parent scope | | save_declaration | Save the current draft (this is not submission) | | print_declaration | Generate a review-PDF job |

set_field and insert_list_entry validate the runtime scope before writing. print_declaration returns job metadata by default; PDFs can contain taxpayer data and are not written into the repository.

Configuration

The live tools authenticate with two independent credential sets, supplied as environment variables:

| Variable | Required | Description | | --- | --- | --- | | ETAX_LOGIN_EMAIL | yes | Keycloak login email | | ETAX_LOGIN_PASSWORD | yes | Keycloak login password | | ETAX_DECLARATION_PERS_ID | yes | PersID from the tax letter (for create_declaration) | | ETAX_DECLARATION_ACCESS_CODE | yes | Zugangscode eFiling from the tax letter | | ETAX_DECLARATION_ID | no | Pin a declaration so editing tools can omit id | | ETAX_LANGUAGE | no | Declaration language; defaults to de |

Credentials are read from the environment only — never pass logins, PersIDs, or access codes as tool arguments.

Environments

| environment | Base URL | | --- | --- | | training | https://schulen-lu.etax.ch | | production | https://esteuern.lu.ch |

This version is optimized for a single configured taxpayer and an optional configured declaration.

Privacy

This repository must stay free of real tax data. Do not commit declarations, annex PDFs, credentials, access codes, bearer tokens, declaration IDs, AHV numbers, or any taxpayer PII. Generated .lunp2024 archives are git-ignored and should be treated as sensitive local artifacts unless built entirely from synthetic input.

Scope

Submission, export, attachment upload, browser OAuth, durable token storage, multi-taxpayer operation, and full .lunp2024 import/export are intentionally out of scope.

License

MIT © Dominic Wörner