elster-mcp-server
Use this MCP server to prepare German ELSTER tax returns (ESt, EÜR, UStVA, and other forms) by filling fields by Kennzahl, checking with ELSTER, reviewing, uploading receipts, and reading past filings—without the form engine submitting; final send is a user handoff, though legacy UStVA tools include a gated confirm.
Start or continue forms: pick year, Anlagen, Datenübernahme, eDaten import, drafts.
Read/crawl form pages: fields, labels, Kennzahlen, repeat groups, navigation RIDs.
Edit forms: set fields/checkboxes/selects by Kennzahl or name; add/delete table rows; press allowlisted commands; save as draft.
Validate: run ELSTER Prüfen, get errors/hints and provisional refund/payment.
Review: read the Formular absenden overview row by row, with sources, then return to editing.
Receipts: list and upload PDFs/images to Meine Belege with Belegart and values.
History/data: list submissions, read Übertragungsprotokoll field-by-field, sync inbox/Übermittelte Formulare, fetch eDaten.
UStVA helpers: list Kennziffern, detect §13b reverse charge, generate archival XML.
Setup/session: test login, show redacted config, list/status/cancel sessions.
Legacy UStVA: start a session, pause at AWAITING_CONFIRM, and confirm Absenden explicitly.
Safety: form-engine send, delete, logout are refused; handoff opens the send page for the user to click.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@elster-mcp-server Fill out my UStVA for Q1 2024 and show me the data before I submit."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
elster-mcp-server
An MCP server that lets Claude (or any MCP client) fill in any form on the German tax portal ELSTER: Einkommensteuer with all its Anlagen, EÜR, UStVA, and whatever else the portal offers. You talk through your return; the agent enters it, runs ELSTER's own checks and shows you exactly what would be transmitted.
It cannot submit. When the return is ready, it opens it for you in a visible browser window on the "Formular absenden" page. You read it, and you click "Absenden".
What it can do
Fill any form by Kennzahl. Fields, checkboxes, table rows and sub-pages, through the same HTTP requests the portal's own page sends. No screen scraping, no brittle clicks.
Start or continue. New forms with the Anlagen you pick, drafts from "Meine Formulare", carrying over last year's submission, importing the pre-filled data the tax office already holds (Lohnsteuerbescheinigung, Vorsorge, …).
Check with ELSTER itself. "Prüfen" returns the portal's errors and hints with the pages that cause them, plus the provisional result ("Erstattung: 1.655,21 €").
Review before sending. Reads the final "Formular absenden" overview row by row, including where each value came from (Bescheinigung, Profil, Beleg, earlier filing).
Receipts. Uploads PDFs and images to "Meine Belege" with their Belegart and amounts.
Your history as context. Lists past submissions and reads their Übertragungsprotokoll field by field, so last year's return can inform this year's. Also reads the ELSTER inbox (Bescheide) and "Übermittelte Formulare".
Hand off. Opens the finished form for you to send. See Safety.
Related MCP server: taxme-mcp
Safety
Sending a tax return is your electronic signature. This server is built so that nothing it runs can do it.
Allowlist, not blocklist. Every form command is parsed, must name exactly one command, and that command must be on a fixed list of editing and checking commands. Anything else, including commands nobody has seen yet, is refused. Send, delete draft, delete receipt and log out are not on the list.
The send page is locked. The engine may look at the "Formular absenden" overview (
elster_form_review), but while it is there it can only switch back to editing.Handoff instead of a send button.
elster_form_handoffopens the form in a separate, visible browser, moves it to "Formular absenden", and then disconnects from that window. The MCP keeps no handle on it, so no tool call, token or flag can click "Absenden", not even with an agent running in a permissive mode. Your mouse is the only way to send.Offline self-test.
node tools/engine-selftest.mjschecks the guards against escaped, compound and disguised send commands in a headless Chrome, without logging in.
Quick start
Requirements: Node.js ≥ 18, your ELSTER certificate file (.pfx) and its password.
git clone https://github.com/Infraviored/elster-mcp-server.git
cd elster-mcp-server
npm install # also downloads a bundled Chromium (~150 MB)
npm run build
cp config.example.json config.json # set auth.pfxPath and auth.passwordRegister it with your client, e.g. Claude Code:
claude mcp add elster -e ELSTER_CONFIG_PATH=$PWD/config.json -- node $PWD/dist/index.jsor Claude Desktop (claude_desktop_config.json, template in examples/):
{
"mcpServers": {
"elster": {
"command": "node",
"args": ["/absolute/path/to/elster-mcp-server/dist/index.js"],
"env": { "ELSTER_CONFIG_PATH": "/absolute/path/to/elster-mcp-server/config.json" }
}
}
}Then just ask: "Mach meine EÜR 2025. Hier sind meine Rechnungen …" and run
elster_login_test once if you want to confirm the certificate works first.
A typical session
elster_form_new { form: "est", year: 2025,
anlagen: ["VHauptvordruck", "VAnlageN", "VAnlageVor"] }
→ eDaten imported, lands on the Startseite, returns the page tree
elster_form_page { rid: "FormData://est-2025-v1/…/VAnlageN[0]/HomeofficePauschale[0]" }
→ fields with Kennzahl, label, current value
elster_form_set { values: { E0204507: 81 } }
elster_form_add_row{ group: "AufwendungenArbeitsmittel",
values: { E0204401: "Bürostuhl", E0204402: 429 } }
elster_form_check → { ok: true, result: ["Erstattung: 1.655,21 €"] }
elster_form_review → every row that would be transmitted, with its source
elster_form_handoff→ a browser window opens on "Formular absenden" — you click
elster_form_handoff_wait
→ returns when you close the window: Transferticket,
protocol saved as HTML + PDFTools
Group | Tool | What it does |
Forms |
| Starts any form: year, Datenübernahme, Anlagen, eDaten import |
| Lists saved drafts / opens one | |
| Reads one page / walks a whole form (fields, repeat groups, navigation) | |
| Sets fields by Kennzahl or full field name | |
| Adds or removes table rows | |
| Uploads PDF/XML files into a form's attachments (e.g. Einspruch "Anhänge") | |
| Escape hatch for other allowlisted form commands | |
| Saves the form as a draft and closes it | |
Check |
| Runs "Prüfen": errors, hints, provisional result |
| Reads the "Formular absenden" overview row by row | |
| Opens the form on "Formular absenden" in a visible window; you send | |
| Waits until you close that window; if you sent, saves the transmission protocol as HTML + PDF | |
Data |
| Pre-filled data the tax office holds for a year |
| Earlier submissions a new form can carry over | |
| Lists / uploads receipts in "Meine Belege" | |
History |
| Past submissions and their full transmitted content |
| Saves a submission's Übertragungsprotokoll as HTML + PDF, as proof | |
| "Übermittelte Formulare" and the inbox, optionally with PDFs | |
Setup |
| Checks the login / shows the config (password redacted) |
UStVA helpers |
| Kennziffer reference, §13b detection, XML snapshot for your archive (never transmitted) |
How it works
The ELSTER Online-Formular is an ordinary HTML form. Every "Nächste Seite", every table
row and every "Prüfen" is a POST of fields[<name>] values plus a JSON command
(reqCmd), and the response is the next page. The server logs in once with Puppeteer and
then replays exactly those requests with fetch from inside the logged-in tab. The tab
itself is never navigated again, which keeps it fast and immune to the portal's modals.
Field names embed ELSTER's Kennzahl (…HomeofficeE0204507), so the agent addresses
fields by the numbers printed on the paper form. Details, wire format and the portal
quirks learned along the way are in CLAUDE.md and
MCP-FINDINGS.md.
Configuration
config.json (path via ELSTER_CONFIG_PATH, default ./config.json); every key can be
overridden by an environment variable: ELSTER_PFX_PATH, ELSTER_PASSWORD,
ELSTER_HEADLESS, ELSTER_DOWNLOAD_DIR, ELSTER_SCREENSHOT_DIR, and the taxpayer and
§13b supplier settings used by the UStVA helpers (see config.example.json). Env vars
win over the file. config.json, *.pfx, downloads/ and screenshots/ are gitignored;
they hold real credentials and tax data.
Limitations
One form can be open per ELSTER session; save before switching (
elster_form_save).The session ends after about 30 idle minutes. The server logs in again by itself, but an unsaved form is then only in ELSTER's own recovery. Save before long pauses.
Money fields labelled "(Euro)" take whole euros only; "(Euro, Cent)" take
3,36.This drives the web portal, not ERiC. Official programmatic submission needs the ERiC library and registration as a software vendor.
Legal notice / Rechtlicher Hinweis
English
This project is an experimental, community-built tool. It is not affiliated with, endorsed by, or supported by the Bundesministerium der Finanzen, the ELSTER project, or any tax authority.
The official, supported way to submit tax data programmatically is the ERiC library (registration as a software vendor required). This tool instead automates the public ELSTER web portal with a real user session — the same path a human user takes — using credentials YOU provide.
The official ELSTER terms of use ("Nutzungsbedingungen") may restrict automated access to the portal. Whether your specific use is permitted is your responsibility to verify before running this software.
Use at your own risk. The author(s) provide this software AS IS, WITHOUT WARRANTY OF ANY KIND (see LICENSE). The author(s) accept NO liability for incorrect tax submissions, account suspensions, missed deadlines, lost data, or any other consequences arising from the use of this software.
This project is not tax advice (no "Hilfeleistung in Steuersachen" in the sense of § 2 StBerG). If you are unsure whether a submission is correct, consult a Steuerberater.
Operators using this software in a commercial context (e.g. submitting on behalf of third parties) may be subject to the German Steuerberatungsgesetz and must verify their own licensing situation.
Deutsch
Dieses Projekt ist ein experimentelles, von der Community gebautes Werkzeug. Es ist weder vom Bundesministerium der Finanzen noch vom ELSTER-Projekt noch von einer Finanzbehörde unterstützt, autorisiert oder geprüft.
Der offizielle, vom BMF unterstützte Weg zur programmatischen Übermittlung von Steuerdaten ist die ERiC-Bibliothek (Registrierung als Softwarehersteller erforderlich). Dieses Tool nimmt stattdessen den Weg über das öffentliche ELSTER-Webportal — denselben Weg, den ein menschlicher Nutzer per Browser geht — mit Zertifikatsdaten, die DU bereitstellst.
Die offiziellen ELSTER-Nutzungsbedingungen können automatisierten Zugriff auf das Portal einschränken oder verbieten. Es liegt in deiner alleinigen Verantwortung zu prüfen, ob dein konkreter Anwendungsfall erlaubt ist, bevor du dieses Tool nutzt.
Nutzung auf eigenes Risiko. Die Autor:innen stellen die Software OHNE JEGLICHE GEWÄHRLEISTUNG bereit (siehe LICENSE). Die Autor:innen übernehmen keine Haftung für fehlerhafte Steuerübermittlungen, gesperrte Konten, versäumte Fristen, Datenverluste oder sonstige Folgen aus der Nutzung dieser Software.
Dieses Projekt ist keine Steuerberatung im Sinne des § 2 StBerG. In Zweifelsfällen ist ein:e Steuerberater:in zu konsultieren.
Wer diese Software gewerblich einsetzt (z.B. Übermittlung im Auftrag Dritter), unterliegt unter Umständen dem Steuerberatungsgesetz und muss seine Berechtigung selbst sicherstellen.
Origin
This project started as a fork of lukasschwarz/elster-mcp-server by Lukas Schwarz, which automated UStVA, EÜR and ESt by clicking through the portal. The form engine replaced that approach entirely, so the fork was detached into its own repository. Thanks to Lukas for the groundwork (login, submission history, inbox sync); his MIT copyright notice is kept in LICENSE.
Contributing
Issues and PRs are welcome. Most useful: reports of forms or pages the engine does not
handle yet (the output of elster_form_page on that page helps), and selftest cases for
the guards. Run npm run build && node tools/engine-selftest.mjs before sending a PR
that touches engine.ts or engine-driver.ts.
License
Available Tools
32 toolselster_belege_listA
Lists receipts in "Meine Belege" (id, label, year, Belegart, recognised values, status). Read-only.
Inputs: year.
elster_beleg_uploadA
Uploads one receipt file (PDF, PNG or JPG, max 10 MB) to "Meine Belege" and tags it with a Belegart and its values, so it is linked to the matching form line. Belegart is a path like "N/Arbeitsmittel" (fields Art_der_Arbeitsmittel, Betrag), "N/Weitere_Wk/Sonst" (Bezeichnung, Betrag), "N/Fortb" (Bezeichnung, Betrag), "N/Dienstreise". Betrag as number or "12,99". Stores a document in the account; submits nothing. Receipts are optional for the ESt (Belegvorhaltepflicht) but can avoid queries.
Inputs: file (required), year (required), fields (required), belegart (required), +3 more.
elster_config_showA
Shows the currently loaded ELSTER configuration (with secrets redacted) so you can verify env vars / config.json were picked up.
Inputs: no named parameters.
elster_datenuebernahme_listA
Lists the earlier submissions ELSTER offers to carry over ("Datenübernahme") for a given form and tax year, without starting a filling session. Read-only. Feed an aufgabeId or year from the result into the "takeover" argument of elster_ustva_start / elster_eur_start / elster_est_start.
Inputs: form (required), year (required).
elster_drafts_listA
Lists saved drafts ("Meine Formulare → Entwürfe") with their aufgabeId, newest first. Uses the persistent engine session (logs in on first use, then stays logged in).
Inputs: no named parameters.
elster_edaten_fetchA
Retrieves the pre-filled tax data ("vorausgefüllte Steuererklärung" / eDaten) the tax authority already holds for a year: Lohnsteuerbescheinigung, Vorsorgeaufwendungen, Lohnersatzleistungen, Riester/Rürup. ELSTER only exposes these from inside the ESt form, so this walks the form up to the import step and reads the values back. The form is left without saving, so no draft is kept (ELSTER may offer it for recovery at the next login). Nothing is ever transmitted.
Inputs: year (required), anlagen.
elster_est_startA
Starts an ESt 1 A (Einkommensteuererklärung) form-prep session. Opens the form, fills taxpayer basics from config + any extra fields you provide (by ELSTER input id/name hint), runs Prüfung, then waits 30 min for you to review in the portal. NEVER submits.
Inputs: year (required), data, takeover.
elster_eur_startA
Starts an EÜR (Anlage Einnahmen-Überschuss-Rechnung) form-prep session. Fills the form up to Prüfung, then tries to "Speichern und Verlassen" so the draft survives in ELSTER. NEVER submits.
Inputs: data (required), year (required), takeover.
elster_form_add_rowA
Adds one row to an inline repeat group ("Mzb", e.g. Arbeitsmittel "AufwendungenArbeitsmittel") by filling its new-row template and committing it ("Eintrag übernehmen"). Group names and template keys come from elster_form_page → groups. Same key and money rules as elster_form_set.
Inputs: group (required), values (required), rid.
elster_form_checkA
Runs ELSTER's "Prüfen" on the open form. Returns ok, the headline (for ESt it includes the provisional "Erstattung/Nachzahlung"), and the error panel with the causing pages. Never sends.
Inputs: no named parameters.
elster_form_crawlA
Walks every page below a RID (breadth-first, read-only) and returns each page's fields and repeat groups. Use it once per form/Anlage to learn which Kennzahl lives on which page.
Inputs: rootRid (required), maxPages.
elster_form_delete_rowC
Deletes row index (0-based) of an inline repeat group on a page.
Inputs: group (required), index (required), rid.
elster_form_newA
Starts a NEW form: picks the year, handles Datenübernahme (none by default), Anlagenauswahl and the eDaten import, and stops on the form's Startseite. Returns the page like elster_form_page. Follow with elster_form_save to persist it as a draft.
Inputs: form (required), year (required), anlagen, takeover, +1 more.
elster_form_openA
Opens a saved draft in the engine session and returns its Startseite (fields, repeat groups, navigation RIDs). Without aufgabeId the newest draft is opened. If ELSTER still holds the form open from an earlier call, it is re-entered instead of failing. Only one form can be open at a time.
Inputs: aufgabeId.
elster_form_pageA
Reads a page of the open form. With rid, jumps there first (RIDs look like "FormData://est-2025-v1/Startseite[0]/MAVSAnlageN[0]/VAnlageN[0]/HomeofficePauschale[0]" and come from the nav list of any page). Returns plain fields (name, kennzahl, label, value, options), repeat groups (committed rows, the template fields for a new row, sub-page RIDs), non-navigation commands, validation errors and the nav RIDs visible from this page. Read-only.
Inputs: rid.
elster_form_pressB
Escape hatch: presses a button by id or posts a raw reqCmd JSON from elster_form_page → commands (e.g. EditDetachedMzbSemIndex to add an Anlage for a person, FillInProfile, AddMzbItem). Sending, deleting drafts and logging out are refused.
Inputs: rid, command, buttonId.
elster_form_reviewA
Final check before the user submits: runs "Prüfen" and, only if it is clean, reads ELSTER's "Formular absenden" overview — exactly the data that would be transmitted, including eDaten fields — as sections of rows (Zeile, label, value, Kennzahl, source). Returns to edit mode in the same call. Never transmits: "Absenden" stays refused, and no command but EINGABE/PRUEFEN is accepted while on the overview.
Inputs: no named parameters.
elster_form_saveA
Saves the open form as a draft ("Speichern und Formular verlassen") and closes it. Reopen with elster_form_open. The server session times out after ~30 min idle and unsaved work is then only in ELSTER's auto-recovery — save before long pauses.
Inputs: no named parameters.
elster_form_setA
Sets plain fields on a page and saves them to the server-side form. Keys are a Kennzahl ("E0204507") or the field name ("eruNWkHomeofficeE0204507"); a key must match exactly one field on the page. Checkboxes take true/false, radios and selects take the option value. Money: fields labelled "(Euro)" accept whole euros only (no decimal separator — round expenses up, income down); "(Euro, Cent)" fields take "3,36". Validation errors come back in errors (HTTP is always 200). Sub-pages of detached repeat groups (e.g. ".../MZBErsteTaetigkeitsstaette[0]") are set with this tool too; jumping to index [n] of such a group creates entry n.
Inputs: values (required), rid.
elster_kennziffern_listA
Returns the list of supported UStVA Kennziffern (codes 81, 86, 66 etc.) with descriptions and whether they are NET (base amount) or TAX (tax amount).
Inputs: no named parameters.
elster_login_testA
Verifies that the configured certificate + password can log into the ELSTER portal. Returns success and final URL or an error. Use this once before submitting anything.
Inputs: no named parameters.
elster_session_cancelC
Cancels a running session (closes the browser, marks status as CANCELLED).
Inputs: sessionId (required).
elster_session_listA
Lists all currently tracked sessions (USTVA / EUR / EST / SYNC) with their status.
Inputs: no named parameters.
elster_session_statusB
Returns the current status, progress log, and any screenshot path for a session started via elster_ustva_start / elster_eur_start / elster_est_start.
Inputs: sessionId (required).
elster_submission_protocolA
Reads the "Übertragungsprotokoll" of already-submitted returns — every field that was actually filed, with its Zeile number, label, value and ELSTER field id — so earlier years can be used as context. Select either by nachrichtId (from elster_submissions_list) or by formFilter/years. Read-only; returns real personal tax data.
Inputs: limit, years, formFilter, nachrichtId.
elster_submissions_listA
Lists everything under "Meine Formulare" → "Übermittelte Formulare": what was filed, when, its Ordnungskriterium, plus the aufgabeId to reuse it as a Datenübernahme source and the nachrichtId needed by elster_submission_protocol. Read-only.
Inputs: formFilter.
elster_sync_historyC
Reads "Übermittelte Formulare" (transmission history) from ELSTER. Optionally downloads PDFs.
Inputs: years, downloadPdfs.
elster_sync_inboxC
Reads ELSTER inbox messages ("Posteingang"). Optionally downloads each message as PDF.
Inputs: maxPages, downloadPdfs.
elster_ustva_confirmA
Confirms submission of a UStVA session that is in AWAITING_CONFIRM state. Triggers the final "Absenden" click. Returns the transmission ticket on success.
Inputs: sessionId (required).
elster_ustva_detect_reverse_chargeC
Tests whether a voucher would be detected as Reverse-Charge (§13b UStG) based on the configured supplier patterns. Returns matched supplier and region (EU / NON_EU), or null.
Inputs: contactName, description.
elster_ustva_generate_xmlA
Generates an ELSTER UStVA XML snapshot for archiving. Does NOT submit (submission goes via elster_ustva_start). Useful for audit trails.
Inputs: year (required), period (required), report (required).
elster_ustva_startA
Starts a UStVA submission session. Opens a browser, logs in, fills the form, runs Prüfung, then PAUSES at AWAITING_CONFIRM. You must explicitly call elster_ustva_confirm to send. Returns a sessionId — poll status via elster_session_status.
Inputs: year (required), period (required), report (required), takeover.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 32 tools
Most tools target clearly distinct actions (form_set vs form_add_row vs form_delete_row, ustva_start vs est_start vs eur_start), but several have overlapping read purposes: elster_sync_history and elster_submissions_list both read the same 'Übermittelte Formulare' area, elster_form_check is a subset of elster_form_review, and elster_form_crawl overlaps elster_form_page. Descriptions are detailed enough to mitigate most misselection, but the duplication is real.
Names consistently use snake_case with an elster_ prefix and a domain segment (form_, ustva_, session_, sync_), making the pattern predictable. Minor deviations: singular vs plural of the same noun (beleg_upload / belege_list, submission_protocol / submissions_list).
32 tools is on the heavy side even for a genuinely complex domain spanning ESt/EÜR/UStVA forms, browser sessions, receipts, drafts, and sync. Several tools look consolidatable (session_list vs session_status, submissions_list vs sync_history, check vs review), pushing it past a comfortably scoped surface.
Coverage is broad: login/config checks, form lifecycle (open/new/page/set/add/delete/save/check/review), UStVA-specific helpers, receipts list/upload, eDaten fetch, drafts, and submission history/protocol. Gaps are minor and partly by design (submission deliberately limited to UStVA; no receipt deletion/update, no explicit logout).
Maintenance
Related MCP Connectors
German tax-firm workflows: clients, deadlines, documents, time tracking and DATEV data via OAuth.
Brazilian fiscal MCP server - issue NF-e, NFC-e, NFS-e, CT-e, MDF-e and DC-e via SEFAZ.
Secure remote MCP for supported accounting workflows in authorized Money S3 companies.
wFirma.pl (Polish accounting) via MCP: invoices, contractors, payments, reports. Full read-write.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that allows AI assistants like Claude to automate interactions with the German tax portal ELSTER via Puppeteer, including form filling, submission, and session management.1451 npm34MIT
- AlicenseAqualityBmaintenanceMCP server for the Canton of Bern tax portal TaxMe/BE-Login that reads account statements and tax returns via Playwright browser automation.1311 npmMIT
- AlicenseNot gradedqualityBmaintenanceA local Windows automation MCP server that lets a KI-Agent safely control the SteuerSparErklärung tax software: inventory and open tax cases, read pages, compare receipts and values, and edit verified working copies, with all ELSTER transmission paths locked tight.MIT

invowerkofficial
AlicenseNot gradedqualityBmaintenanceEnables creating ZUGFeRD PDFs and XRechnung invoices and validating ZUGFeRD/Factur-X, XRechnung (KoSIT), and Peppol BIS e-invoices through an MCP endpoint, returning validation reports.MIT