elster-mcp-server

elster-mcp-server

Claude（またはMCP対応クライアント）がPuppeteer経由でドイツの税務ポータルELSTERを操作できるようにする、Model Context Protocol（MCP）サーバーです。

---

⚖️ 法的通知／Rechtlicher Hinweis

英語

• このプロジェクトは、実験的なコミュニティ開発ツールです。Bundesministerium der Finanzen、ELSTERプロジェクト、またはいかなる税務当局とも提携、推奨、支援関係にありません。
• プログラムから税務データを送信するための公式かつサポート対象の方法は、ERiCライブラリです（ソフトウェアベンダーとしての登録が必要です）。このツールはその代わりに、ユーザーが提供する認証情報を使って、実際のユーザーセッションで公開されているELSTERのウェブポータルを自動操作します。これは、人間のユーザーが利用するのと同じ方法です。
• 公式のELSTER利用規約（「Nutzungsbedingungen」）では、ポータルへの自動アクセスが制限されている場合があります。このソフトウェアを実行する前に、具体的な用途が許可されているかを確認する責任はご自身にあります。
• ご自身の責任でご利用ください。作者は、このソフトウェアを現状有姿で、いかなる種類の保証もなく提供します（LICENSEを参照）。作者は、誤った税務申告、アカウントの停止、期限の徒過、データの損失、その他このソフトウェアの利用によって生じるいかなる結果についても、一切の責任を負いません。
• このプロジェクトは、税務に関する助言ではありません（§ 2 StBerGの意味における「Hilfeleistung in Steuersachen」には該当しません）。申告内容が正しいかどうか不明な場合は、*税務アドバイザー（Steuerberater）*に相談してください。
• このソフトウェアを商業目的で使用する運営者（第三者に代わって申告する場合など）は、ドイツのSteuerberatungsgesetzの適用対象となる可能性があります。各自で必要な資格を確認してください。

ドイツ語

• このプロジェクトは、実験的なコミュニティ開発ツールです。Bundesministerium der Finanzen、ELSTERプロジェクト、またはいかなる税務当局からも、支援、認可、審査を受けていません。
• 税務データをプログラムから送信するための、BMFが支援する公式な方法は、ERiCライブラリです（ソフトウェアメーカーとしての登録が必要です）。このツールはその代わりに、公開されているELSTERウェブポータルを利用します。これは、人間のユーザーがブラウザーから利用するのと同じ方法であり、あなたが提供する証明書情報を使って操作します。
• 公式のELSTER利用規約では、ポータルへの自動アクセスが制限または禁止されている場合があります。このツールを利用する前に、具体的な用途が許可されているかを確認する責任は、全面的にあなたにあります。
• ご自身の責任でご利用ください。作者は、このソフトウェアをいかなる保証もなく提供します（LICENSEを参照）。作者は、誤った税務データの送信、アカウントの停止、期限の徒過、データの損失、その他このソフトウェアの利用によって生じるいかなる結果についても、一切の責任を負いません。
• このプロジェクトは、§ 2 StBerGの意味における税務相談ではありません。疑問がある場合は、税務アドバイザーに相談してください。
• このソフトウェアを商業目的で使用する場合（第三者に代わって送信する場合など）、Steuerberatungsgesetzの適用対象となる可能性があるため、必要な資格を自身で確認してください。

ツールに組み込まれた実用的な安全対策

• 実際にデータを送信する唯一のツールは elster_ustva_confirm です。elster_ustva_start が AWAITING_CONFIRM で一時停止した後、明示的にもう一度呼び出す必要があります。この2回目の確認なしに、データが送信されることはありません。
• 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 の 2 桁の 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 は絶対にコミットしないでください。 デフォルトで gitignore の対象になっています。
• 証明書のパスワードは環境変数または設定ファイルから読み込まれ、Puppeteer に渡されます — このサーバーを実行するホストが信頼できることを確認してください。
• 初回実行時は ELSTER_HEADLESS=false に設定し、画面を確認してすべてが正しく設定されていることを確かめてください。

制限事項

• ELSTER ポータルのセレクターは変更されることがあります。フローが動作しなくなった場合は、ELSTER_HEADLESS=false で実行し、./screenshots/ に保存されたスクリーンショットを確認してください。
• ESt ツールは意図的に薄いラッパーとして実装されています — ドイツの所得税申告書（Anlage G、V、N、S、KAP …）には、何千ものフィールドがある数十種類の様式が含まれます。このサーバーが提供するのはフレームワーク（ログイン、フォームを開く、ラベルまたは ID による入力、Prüfen）であり、入力するフィールドはユーザーが選択します。
• XML による送信には対応していません。公式なプログラム送信には ERiC ライブラリが必要です（ソフトウェアベンダーとしての登録が必要です）。このサーバーは、納税者が利用するものと同じオンラインフォームの経路を使用します。

ライセンス

MIT

コントリビューション

PR を歓迎します。特に役立つ追加内容は次のとおりです。

1. 変更された ELSTER ページに対応する、より堅牢なセレクター
2. ESt 用の事前入力済み Anlage G / V / N / S テンプレート
3. elster_ustva_* 用の型付き report スキーマバリデーター

イシューを作成する際は、ELSTER_HEADLESS=false を指定して実行し、失敗を示すスクリーンショットを ./screenshots/ に保存して添付してください。