# elster-mcp

Let Claude check and file German tax data through ELSTER, using the official ERiC library on your own machine.

![Python](https://img.shields.io/badge/python-3.13-informational) ![ERiC](https://img.shields.io/badge/ERiC-45.1.5.0-informational) ![Status](https://img.shields.io/badge/status-test%20mode-yellow) ![License](https://img.shields.io/badge/license-source--available-lightgrey)

> **Source-available, not open source.** Free for individuals to run and study with credit kept intact. Business or client use, and any derivative work including one generated by an AI, needs written consent. See [LICENSE](LICENSE). For a commercial licence or setup help, reach out through [next8n.com](https://next8n.com).

## What you get

- **Catch mistakes before ELSTER does.** Tax ID, IBAN and tax-number checks run offline with the same rules ELSTER uses.
- **Find your tax office in seconds.** List every Finanzamt per federal state and look one up by number.
- **Know your certificate is still good.** See when your ELSTER certificate expires, without opening the ELSTER portal.
- **Validate a return before you send it.** ERiC checks the XML locally and can write a preview PDF.
- **File safely.** Submissions are test-only by default. A real filing needs the operator flag and your explicit approval of that exact return.

## From install to first result

1. Download ERiC from the ELSTER developer area and extract the archive.
2. Register the server with Claude Code.
   ```bash
   claude mcp add elster -s user \
     -e ERIC_HOME=/path/to/ERiC-45.1.5.0/Darwin-universal \
     -e ELSTER_CERT_PATH=/path/to/your-certificate.pfx \
     -e ELSTER_CERT_PASSWORD_CMD="your-secret-manager command that prints the password" \
     -- uv run --directory /path/to/elster-mcp elster-mcp
   ```
3. Ask Claude to check your ELSTER setup and tell you when your certificate expires.

## Tools

| Tool | What it does | Contacts ELSTER |
|---|---|---|
| `elster_system_check` | ERiC loads, what is configured | no |
| `elster_check_tax_id` | Validate a tax ID (IdNr) | no |
| `elster_check_iban` | Validate an IBAN | no |
| `elster_check_tax_number` | Validate a 13-digit ELSTER tax number | no |
| `elster_convert_tax_number` | Tax number from a notice to ELSTER format | no |
| `elster_list_states` | Federal-state numbers | no |
| `elster_list_tax_offices` | Tax offices of one state | no |
| `elster_tax_office_info` | Details of one tax office | no |
| `elster_list_test_tax_offices` | Test tax offices for test filings | no |
| `elster_certificate_info` | Certificate validity, password never returned | no |
| `elster_validate_return` | Validate a return locally, optional preview PDF | no |
| `elster_submit_return` | Send a return, test mode by default | **yes** |

## Configuration

| Variable | Required | Meaning |
|---|---|---|
| `ERIC_HOME` | yes | Extracted ERiC platform folder (contains `lib/`) |
| `ELSTER_CERT_PATH` | for certificate and sending | Your `.pfx` certificate |
| `ELSTER_CERT_PASSWORD_CMD` | for certificate and sending | Command that prints the password (preferred) |
| `ELSTER_CERT_PASSWORD` | alternative | The password itself |
| `ELSTER_HERSTELLER_ID` | to validate or send returns | Your own Hersteller-ID, the ERiC sample ID 74931 is refused |
| `ELSTER_ALLOW_LIVE` | no | `1` allows real filings, off by default |
| `ELSTER_LOG_DIR` | no | ERiC log folder, default `~/.elster-mcp/logs` |

## Development

```bash
uv sync
uv run pytest      # integration tests against the real ERiC library
uv run ruff check .
```

## Legal

- ERiC and its Python sample wrapper are provided free of charge by the Bayerisches Landesamt für Steuern under their own licence. Neither is part of this repository. elster-mcp loads the wrapper from your own ERiC download at runtime, so you obtain ERiC, accept its licence yourself, and keep it on the current minimum version.
- The ERiC documentation, schemas and sample returns are not covered by the ERiC licence for redistribution. Never commit them here; `.gitignore` and CI block them.
- ELSTER needs your own Hersteller-ID for every return, even an offline check. ERiC refuses the sample ID with error 610301202.
- Keep your own backups of every return you prepare or send.
- Only file returns for the certificate holder. Preparing returns for other people is reserved for tax advisors (StBerG).
- ELSTER is a registered trademark of the Freistaat Bayern. This project is not affiliated with or endorsed by the tax administration. See [docs/TRADEMARKS.md](docs/TRADEMARKS.md).

## Privacy notice from the tax administration

The ERiC licence requires that end users see this notice before using software built on ERiC:

> Datenschutzhinweis durch die Finanzverwaltung: "Mit dieser Software werden personenbezogene Daten im Sinne des Art. 4 Nr. 1 Datenschutzgrundverordnung (DSGVO) und Art. 9 Abs. 1 DSGVO zum Zwecke der Verarbeitung erhoben. Neben den reinen Daten, die zur Steuerveranlagung benötigt werden, erhebt die Software Daten über die Art des Betriebssystems des Nutzers und übermittelt diese an die Finanzverwaltung. Diese Daten werden benötigt, um die ordnungsgemäße Verarbeitung der Daten sicherzustellen und Fehlern im Verarbeitungsprozess vorzubeugen. Die Nutzung der Daten erfolgt im Rahmen des Art. 6 Abs. 1 UAbs. 1 Buchst. e i.V.m. Abs. 3 UAbs. 1 Buchst. b DSGVO i.V.m. bundes- bzw. landesgesetzlicher Steuergesetze durch die Finanzverwaltung und nur für den genannten Zweck."

The tax administration's full GDPR information letter (Articles 12 to 14) ships as Annex 2 of `lizenz.pdf` in your ERiC download. Read it before your first submission.

## License

Source-available under the [ELSTER-MCP Source-Available License](LICENSE). Not open source and not MIT. Built by Mirza Iqbal. Questions, configuration help, or a commercial licence through [next8n.com](https://next8n.com).