elster-mcp-server

elster-mcp-server

一个模型上下文协议（MCP）服务，可让 Claude（或任何支持 MCP 的客户端） 通过 Puppeteer 操作德国税务门户 ELSTER。

---

⚖️ 法律声明 / 法律提示

英语

• 本项目是一个实验性的社区开发工具。它与德国联邦财政部、ELSTER 项目或任何税务机关均无关联，也未获得其认可或支持。
• 以编程方式提交税务数据的官方支持途径是 ERiC 库（需要注册为软件供应商）。本工具则使用你提供的凭据，通过真实用户会话自动操作公开的 ELSTER 网站门户——与普通用户采取的途径相同。
• ELSTER 官方**使用条款（“Nutzungsbedingungen”）**可能限制自动访问门户。运行本软件之前，你有责任确认自己的具体用途是否获得许可。
• 使用风险自负。 作者按**“现状”提供本软件，不作任何形式的担保（请参阅 LICENSE）。对于因使用本软件而导致的错误税务申报、账户停用、错过截止日期、数据丢失或任何其他后果，作者不承担任何责任**。
• 本项目不提供税务建议（不属于 § 2 StBerG 所指的“税务事务协助”）。如果你不确定申报是否正确，请咨询 Steuerberater。
• 在商业场景中使用本软件的运营者（例如代表第三方提交申报）可能受德国 Steuerberatungsgesetz 约束，并必须自行确认其许可资质。

德语

• 本项目是一个实验性的社区开发工具。它既未获得德国联邦财政部、ELSTER 项目或任何税务机关的支持、授权或审核。
• 以编程方式提交税务数据的官方且受德国联邦财政部支持的途径是 ERiC 库（需要注册为软件开发商）。本工具则使用你提供的证书数据，通过公开的 ELSTER 网站门户操作——与用户通过浏览器自行办理的途径相同。
• ELSTER 官方使用条款可能限制或禁止自动访问门户。在使用本工具之前，确认你的具体用途是否获准，完全由你自行负责。
• 使用风险自负。 作者按不提供任何担保的方式提供本软件（请参阅 LICENSE）。对于因使用本软件而导致的错误税务申报、账户停用、错过截止日期、数据丢失或其他后果，作者不承担任何责任。
• 本项目不提供税务咨询，不属于 § 2 StBerG 所指的税务咨询。如有疑问，请咨询税务顾问。
• 将本软件用于商业目的的人员（例如代表第三方提交申报）可能受《税务咨询法》约束，必须自行确认具备相应资质。

工具内置的实用防护措施

• 唯一实际传输数据的工具是 elster_ustva_confirm——在 elster_ustva_start 暂停于 AWAITING_CONFIRM 后，必须再次显式调用该工具。未经这第二次确认，不会发送任何数据。
• EÜR 和 ESt 工具绝不会提交。它们只会填写表单，直到“Prüfen”步骤，然后停止，让你在 ELSTER 门户中自行检查并提交。
• 所有同步、历史记录和收件箱工具均为只读，不会修改 ELSTER 端的状态。

---

功能

工具	功能说明	是否提交？
elster_login_test	验证你的证书和密码能否登录	否
elster_config_show	显示已加载的配置（机密信息已隐藏）	否
elster_kennziffern_list	返回受支持的 UStVA Kennziffern 及其说明	否
elster_ustva_generate_xml	生成 UStVA XML 快照（仅存档）	否
elster_ustva_detect_reverse_charge	检测 §13b 反向征税供应商	否
elster_ustva_start	登录、填写、运行 Prüfung，然后暂停等待确认	暂停
elster_ustva_confirm	在你审核后点击 "Absenden"	是
elster_eur_start	填写 Anlage EÜR 直到 Prüfung，然后点击 "Speichern und Verlassen"	否
elster_est_start	打开 ESt 1 A，填写基本信息，运行 Prüfung，并保持浏览器打开 30 分钟	否
elster_sync_history	读取 "Übermittelte Formulare"（可选包含 PDF）	否
elster_sync_inbox	读取 ELSTER 收件箱（可选包含 PDF）	否
elster_session_status / _list / _cancel	会话管理	否

要求

• Node.js ≥ 18
• ELSTER 证书文件（.pfx）——从 https://www.elster.de → "Mein ELSTER" → "Mein Benutzerkonto" → "Zertifikat verlängern" 获取
• 证书密码
• 你的 Steuernummer 和 Bundesland-Code

安装

git clone https://github.com/YOUR_USERNAME/elster-mcp-server.git
cd elster-mcp-server
npm install
npm run build

Puppeteer 会在首次安装时安装捆绑的 Chromium（约 150 MB）。

配置

cp config.example.json config.json
$EDITOR config.json

config.json 中的所有键都可以通过环境变量覆盖 （ELSTER_PFX_PATH、ELSTER_PASSWORD、ELSTER_TAX_NUMBER、 ELSTER_STATE_CODE、ELSTER_NAME、ELSTER_FIRST_NAME、ELSTER_STREET、 ELSTER_HOUSE_NUMBER、ELSTER_ZIP、ELSTER_CITY、ELSTER_COUNTRY、 ELSTER_DOWNLOAD_DIR、ELSTER_SCREENSHOT_DIR、ELSTER_HEADLESS、 ELSTER_EST_SKIP_EUR）。环境变量优先于文件中的值。

你也可以通过 ELSTER_CONFIG_PATH=/path/to/your/config.json 指定其他配置文件。

你的 Finanzamt 对应的两位数 stateCode 由 ELSTER 发布—— 请在 ELSTER 官方文档中查找当前值。

反向征税供应商列表

在 config.json 的 ustva.reverseChargeSuppliers 下添加你的 §13b UStG 供应商。 匹配规则是不区分大小写的正则表达式，会针对凭证的 contactName 或 description 进行匹配。示例条目：

{ "pattern": "your-supplier\\s+ireland", "region": "EU", "name": "Your Supplier Ireland" }

与 Claude Desktop 配合使用

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "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"
      }
    }
  }
}

模板参见 examples/claude_desktop_config.json。

与任意 MCP 客户端配合使用

以 stdio 模式运行服务：

node dist/index.js

然后通过客户端的 MCP 传输方式连接。

典型的 UStVA 流程

1. elster_login_test                          → { ok: true }
2. elster_kennziffern_list                    → reference for valid codes
3. elster_ustva_start({                       → { sessionId: "ustva-..." }
     year: 2026,
     period: "Q1",
     report: { "81": 12000, "86": 300, "66": 1845.30 }
   })
4. elster_session_status({ sessionId })       → poll until status == AWAITING_CONFIRM
   (open the screenshot at screenshotPath to verify)
5. elster_ustva_confirm({ sessionId })        → { success: true, ticket: "..." }

典型的 EÜR 流程

1. elster_login_test
2. elster_eur_start({
     year: 2025,
     data: {
       betriebseinnahmen: 50000,
       fahrzeugkosten: 1200,
       afa: 800,
       homeOffice: 1260
     }
   })
3. elster_session_status (poll until SAVED or AWAITING_REVIEW)
4. open the ELSTER portal in your browser → "Meine Formulare" → review the draft → submit manually

安全说明

• 切勿提交你的 .env、config.json 或 .pfx。 默认情况下，这些文件已被 git 忽略。
• 证书密码会从环境变量或配置中读取并传递给 Puppeteer——请确保运行此服务的主机可信。
• 首次运行时，将 ELSTER_HEADLESS=false 设置一次，以观察运行过程并确认所有配置均已正确连接。

限制

• ELSTER 门户的选择器可能会变化。如果流程中断，请使用 ELSTER_HEADLESS=false 运行，并检查写入 ./screenshots/ 的截图。
• ESt 工具有意设计为轻量封装——德国所得税表格（Anlage G、V、N、S、KAP 等）有数十种，包含数千个字段。此服务提供框架（登录、打开、按标签或 ID 填写、Prüfen），而字段选择由你决定。
• 不支持 XML 提交。官方程序化提交需要 ERiC 库（需注册为软件供应商）。此服务使用与所有纳税人相同的 Online-Formular 流程。

许可证

MIT

贡献

欢迎提交 PR。最有用的补充包括：

1. 为改版后的 ELSTER 页面提供更可靠的选择器
2. 为 ESt 提供预填的 Anlage G / V / N / S 模板
3. 为 elster_ustva_* 提供类型化的 report 架构验证器

提交 issue 时，请使用 ELSTER_HEADLESS=false 运行，并附上 ./screenshots/ 下显示故障的截图。