内容
# elster-mcp-server
一款 **模型上下文协议（MCP）服务器**，允许 Claude（或任何支持 MCP 的客户端）通过 Puppeteer 驱动德国税务门户网站 [ELSTER](https://www.elster.de)。
---
## ⚖️ 法律声明 / Rechtlicher Hinweis
**中文**
- 本项目是一个 **实验性、社区建设的工具**。它 **不隶属于、不支持、不背书** 联邦财政部、ELSTER 项目或任何税务机关。
- 官方支持的编程提交税务数据的方式是 **ERiC 库**（需要注册为软件供应商）。该工具通过 Puppeteer 自动化公共 ELSTER **网页门户**，使用您提供的凭证，以人类用户的相同路径进行。
- 官方 ELSTER **使用条款（"Nutzungsbedingungen"）** 可能会限制或禁止对门户网站的自动化访问。您有 **责任自行验证** 在运行此软件之前，您的具体使用是否被允许。
- **自担风险**。作者提供此软件 **不附带任何保证**（参见 [LICENSE](LICENSE)）。作者 **不承担任何责任**，包括但不限于错误的税务提交、账户冻结、截止日期错过、数据丢失或因使用此软件而产生的其他后果。
- 本项目 **不是税务咨询**（不是 § 2 StBerG 中的 "Hilfeleistung in Steuersachen"）。如果您不确定提交是否正确，请咨询 **税务顾问**。
- 在 **商业环境**中使用此软件（例如代表第三方提交）可能受德国 **税务咨询法** 的约束，您必须自行验证您的许可情况。
## 特性
| 工具 | 功能 | 是否提交？ |
|------|--------------|----------|
| `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` | 登录、填写、运行检查，然后 **暂停等待确认** | 暂停 |
| `elster_ustva_confirm` | 在您审查后点击 "Absenden" | **是** |
| `elster_eur_start` | 填写 Anlage EÜR 直到检查，然后 "保存并离开" | 否 |
| `elster_est_start` | 打开 ESt 1 A、填写基本信息、运行检查、保持浏览器打开 30 分钟 | 否 |
| `elster_sync_history` | 读取 "已提交的表格"（可选带 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" 获取
- 证书密码
- 您的 **税务编号** 和 **联邦州代码**
## 安装
```bash
git clone https://github.com/YOUR_USERNAME/elster-mcp-server.git
cd elster-mcp-server
npm install
npm run build
```
Puppeteer 将在首次安装时安装一个捆绑的 Chromium（约 150 MB）。
## 配置
```bash
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`
指定不同的配置文件路径。
两位数字的 `stateCode` 表示您的 Finanzamt，由 ELSTER 公布 —
在官方 ELSTER 文档中查找当前值。
### 反向收费供应商列表
在 `config.json` 中，将您的 §13b UStG 供应商添加到 `ustva.reverseChargeSuppliers` 下。
模式是与代金券的 `contactName` 或 `description` 匹配的不区分大小写的正则表达式。示例条目：
```json
{ "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）：
```json
{
"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 客户端一起使用
在标准输入/输出模式下运行服务器：
```bash
node dist/index.js
```
然后通过客户端的 MCP 传输连接。
## 典型的 UStVA 流程
```text
1. elster_login_test → { ok: true }
2. elster_kennziffern_list → 有效代码的参考
3. elster_ustva_start({ → { sessionId: "ustva-..." }
year: 2026,
period: "Q1",
report: { "81": 12000, "86": 300, "66": 1845.30 }
})
4. elster_session_status({ sessionId }) → 轮询直到状态 == AWAITING_CONFIRM
（打开 screenshotPath 处的截图进行验证）
5. elster_ustva_confirm({ sessionId }) → { success: true, ticket: "..." }
```
## 典型的 EÜR 流程
```text
1. elster_login_test
2. elster_eur_start({
year: 2025,
data: {
betriebseinnahmen: 50000,
fahrzeugkosten: 1200,
afa: 800,
homeOffice: 1260
}
})
3. elster_session_status （轮询直到 SAVED 或 AWAITING_REVIEW）
4. 在浏览器中打开 ELSTER 门户网站 → "Meine Formulare" → 查看草稿 → 手动提交
```
## 安全注意事项
- **永远不要提交您的 `.env`、`config.json` 或 `.pfx` 文件**。它们默认被 gitignore。
- 证书密码从环境变量/配置中读取并传递给 Puppeteer — 请确保运行此服务器的主机是受信任的。
- 将 `ELSTER_HEADLESS=false` 设置为一次，以观察第一次运行并确认一切正常。
## 限制
- ELSTER 门户网站选择器可能会更改。如果流程中断，请使用 `ELSTER_HEADLESS=false` 运行，并检查写入 `./screenshots/` 的截图。
- ESt 工具故意是一个薄包装 — 德国所得税表格（Anlage G, V, N, S, KAP …）有数十种不同表格，包含数千个字段。该服务器提供框架
（登录、打开、按标签或 ID 填写、检查），并将字段选择留给您。
- 没有 XML 提交路径。官方编程提交需要 ERiC 库
（注册为软件供应商）。该服务器使用与任何纳税人相同的在线表格路径。
## 许可证
[MIT](LICENSE)
## 贡献
欢迎 PR。最有用的补充是：
1. 针对更改的 ELSTER 页面的更强大的选择器
2. ESt 的预填充 Anlage G / V / N / S 模板
3. `elster_ustva_*` 的类型化 `report` 模式验证器
在打开问题时，请使用 `ELSTER_HEADLESS=false` 运行并附加
在 `./screenshots/` 下显示失败的截图。
