{
  "markdown": "# elster-mcp-server\n\nA **Model Context Protocol (MCP) server** that lets Claude (or any MCP-capable client)\ndrive the German tax portal [ELSTER](https://www.elster.de) via Puppeteer.\n\n---\n\n## ⚖️ Legal Notice / Rechtlicher Hinweis\n\n**English**\n\n- 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.\n- 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.\n- 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.\n- **Use at your own risk.** The author(s) provide this software **AS IS, WITHOUT WARRANTY OF ANY KIND** (see [LICENSE](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.\n- 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*.\n- 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.\n\n**Deutsch**\n\n- 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**.\n- 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.\n- 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.\n- **Nutzung auf eigenes Risiko.** Die Autor:innen stellen die Software **OHNE JEGLICHE GEWÄHRLEISTUNG** bereit (siehe [LICENSE](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.\n- Dieses Projekt ist **keine Steuerberatung** im Sinne des § 2 StBerG. In Zweifelsfällen ist ein:e Steuerberater:in zu konsultieren.\n- Wer diese Software **gewerblich** einsetzt (z.B. Übermittlung im Auftrag Dritter), unterliegt unter Umständen dem Steuerberatungsgesetz und muss seine Berechtigung selbst sicherstellen.\n\n**Practical safeguards built into the tool**\n\n- The only tool that actually transmits data is `elster_ustva_confirm` — it requires an **explicit second call** after `elster_ustva_start` has paused at `AWAITING_CONFIRM`. Nothing is sent without that second confirmation.\n- The EÜR and ESt tools **never submit**. They only fill the form up to \"Prüfen\" and stop, so you review and submit yourself in the ELSTER portal.\n- All sync / history / inbox tools are read-only and never modify state on the ELSTER side.\n\n---\n\n## Features\n\n| Tool | What it does | Submits? |\n|------|--------------|----------|\n| `elster_login_test` | Verifies your certificate + password can log in | No |\n| `elster_config_show` | Shows the loaded config (secrets redacted) | No |\n| `elster_kennziffern_list` | Returns the supported UStVA Kennziffern with descriptions | No |\n| `elster_ustva_generate_xml` | Generates a UStVA XML snapshot (archive only) | No |\n| `elster_ustva_detect_reverse_charge` | Detects §13b reverse-charge suppliers | No |\n| `elster_ustva_start` | Logs in, fills, runs Prüfung, then **pauses for confirmation** | Pauses |\n| `elster_ustva_confirm` | Clicks \"Absenden\" after you reviewed | **Yes** |\n| `elster_eur_start` | Fills Anlage EÜR up to Prüfung, then \"Speichern und Verlassen\" | No |\n| `elster_est_start` | Opens ESt 1 A, fills basics, runs Prüfung, keeps browser open 30 min | No |\n| `elster_sync_history` | Reads \"Übermittelte Formulare\" (optionally with PDFs) | No |\n| `elster_sync_inbox` | Reads ELSTER inbox (optionally with PDFs) | No |\n| `elster_session_status` / `_list` / `_cancel` | Session management | No |\n\n## Requirements\n\n- **Node.js ≥ 18**\n- An **ELSTER certificate file** (`.pfx`) — get it from `https://www.elster.de` → \"Mein ELSTER\" → \"Mein Benutzerkonto\" → \"Zertifikat verlängern\"\n- The certificate password\n- Your **Steuernummer** and **Bundesland-Code**\n\n## Install\n\n```bash\ngit clone https://github.com/YOUR_USERNAME/elster-mcp-server.git\ncd elster-mcp-server\nnpm install\nnpm run build\n```\n\nPuppeteer will install a bundled Chromium on first install (~150 MB).\n\n## Configuration\n\n```bash\ncp config.example.json config.json\n$EDITOR config.json\n```\n\nAll keys in `config.json` can be overridden by environment variables\n(`ELSTER_PFX_PATH`, `ELSTER_PASSWORD`, `ELSTER_TAX_NUMBER`,\n`ELSTER_STATE_CODE`, `ELSTER_NAME`, `ELSTER_FIRST_NAME`, `ELSTER_STREET`,\n`ELSTER_HOUSE_NUMBER`, `ELSTER_ZIP`, `ELSTER_CITY`, `ELSTER_COUNTRY`,\n`ELSTER_DOWNLOAD_DIR`, `ELSTER_SCREENSHOT_DIR`, `ELSTER_HEADLESS`,\n`ELSTER_EST_SKIP_EUR`). Env vars win over the file.\n\nYou can also point the loader at a different config file via\n`ELSTER_CONFIG_PATH=/path/to/your/config.json`.\n\nThe two-digit `stateCode` for your Finanzamt is published by ELSTER —\nlook up the current value in the official ELSTER documentation.\n\n### Reverse-Charge supplier list\n\nAdd your `§13b UStG` suppliers under `ustva.reverseChargeSuppliers` in\n`config.json`. Patterns are case-insensitive regexes matched against the\nvoucher's `contactName` or `description`. Example entry:\n\n```json\n{ \"pattern\": \"your-supplier\\\\s+ireland\", \"region\": \"EU\", \"name\": \"Your Supplier Ireland\" }\n```\n\n## Use with Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`\n(macOS) or `%APPDATA%\\Claude\\claude_desktop_config.json` (Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"elster\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/elster-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"ELSTER_CONFIG_PATH\": \"/absolute/path/to/elster-mcp-server/config.json\"\n      }\n    }\n  }\n}\n```\n\nSee `examples/claude_desktop_config.json` for the template.\n\n## Use with any MCP client\n\nRun the server in stdio mode:\n\n```bash\nnode dist/index.js\n```\n\nThen connect via your client's MCP transport.\n\n## Typical UStVA flow\n\n```text\n1. elster_login_test                          → { ok: true }\n2. elster_kennziffern_list                    → reference for valid codes\n3. elster_ustva_start({                       → { sessionId: \"ustva-...\" }\n     year: 2026,\n     period: \"Q1\",\n     report: { \"81\": 12000, \"86\": 300, \"66\": 1845.30 }\n   })\n4. elster_session_status({ sessionId })       → poll until status == AWAITING_CONFIRM\n   (open the screenshot at screenshotPath to verify)\n5. elster_ustva_confirm({ sessionId })        → { success: true, ticket: \"...\" }\n```\n\n## Typical EÜR flow\n\n```text\n1. elster_login_test\n2. elster_eur_start({\n     year: 2025,\n     data: {\n       betriebseinnahmen: 50000,\n       fahrzeugkosten: 1200,\n       afa: 800,\n       homeOffice: 1260\n     }\n   })\n3. elster_session_status (poll until SAVED or AWAITING_REVIEW)\n4. open the ELSTER portal in your browser → \"Meine Formulare\" → review the draft → submit manually\n```\n\n## Security notes\n\n- **Never commit your `.env`, `config.json`, or `.pfx`.** They are gitignored by default.\n- The certificate password is read from env / config and passed to Puppeteer — make sure\n  the host running this server is trusted.\n- Set `ELSTER_HEADLESS=false` once to watch the first run and confirm everything is wired correctly.\n\n## Limitations\n\n- The ELSTER portal selectors can change. If a flow breaks, run with `ELSTER_HEADLESS=false`\n  and check the screenshots written to `./screenshots/`.\n- The ESt tool is intentionally a thin wrapper — German income-tax forms (Anlage G, V, N, S, KAP …)\n  are dozens of different forms with thousands of fields. This server provides the framework\n  (login, open, fill-by-label-or-id, Prüfen) and leaves the field choices to you.\n- No XML submission path. Official programmatic submission requires the ERiC library\n  (registration as a software vendor). This server uses the same Online-Formular path\n  that any taxpayer uses.\n\n## License\n\n[MIT](LICENSE)\n\n## Contributing\n\nPRs welcome. The most useful additions are:\n\n1. More robust selectors for changed ELSTER pages\n2. Pre-filled Anlage G / V / N / S templates for ESt\n3. A typed `report` schema validator for `elster_ustva_*`\n\nWhen opening an issue, please run with `ELSTER_HEADLESS=false` and attach the\nscreenshot under `./screenshots/` that shows the failure.\n",
  "bytes": 9251,
  "sha": "92ac1806a54e66b97adb90d357a3c059b2a3987b302782b22e98188055b0d311",
  "repo_slug": "lukasschwarz/elster-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_lukasschwarz_elster_mcp_server_f4c51ffb/readme"
}