mcp-ksef-pl

mcp-ksef-pl 🇵🇱

English | Polski

ポーランドの電子請求書に対応し、KSeF（FA(2)）およびPeppol BIS Billing 3.0 / EN 16931に準拠したツールを提供する Python MCP サーバーです。AI エージェント（Claude、IDE）が、請求書の生成、検証、Krajowy System e-Faktur（KSeF）への送信、およびポーランドの納税者識別番号（NIP、REGON）の検証を行えるようにします。

---

はじめに

このパッケージは、欧州の電子請求書 MCP サーバー向け共有基盤ライブラリであるmcp-einvoicing-coreをベースに構築されています。OAuth2 HTTP クライアント、トークンキャッシュ、データモデル、ログユーティリティ、例外階層を提供します。

mcp-einvoicing-coreは依存関係として自動的にインストールされるため、追加の手順は不要です。

インストール

PyPI 経由（推奨）

pip install mcp-ksef-pl

事前にインストールせずにuvxを使うこともできます。

uvx mcp-ksef-pl

ソースから

git clone https://github.com/cmendezs/mcp-ksef-pl.git
cd mcp-ksef-pl
uv sync --all-extras

設定（環境変数）

変数	デフォルト	説明
KSEF_ENVIRONMENT	test	KSeF 環境：productionまたはtest
KSEF_SESSION_TOKEN	—	KSeF セッショントークン（MF とのチャレンジ・レスポンスフローで取得）
KSEF_NIP	—	請求書を送信する事業体の NIP
KSEF_TIMEOUT	30	HTTP リクエストのタイムアウト（秒）
KSEF_VERIFY_MF_KEY_PINNING	false	MF 暗号化証明書に対する SPKI SHA-256 ピンニングを強制します。有効な環境のフィンガープリントが設定されるまでは、trueに設定しても何も行いません
EINVOICING_PEPPOL_CODELIST_DIR	—	Peppol コードリストツールに必要な、OpenPeppol eDEC Code Lists の独自コピーを含むローカルディレクトリ（このパッケージには含まれていません。mcp-einvoicing-core README を参照）
EINVOICING_EN16931_CODELIST_DIR	—	EN 16931 コードリストツールに必要な、CEF「Digital Building Blocks」EN 16931 セマンティックコードリストの独自コピーを含むローカルディレクトリ（同梱されていません。mcp-einvoicing-core README を参照）

EUSR/TSR レポートツールおよび MLS ツールで Schematron 検証を行うには、[xslt2]エクストラ（pip install "mcp-ksef-pl[xslt2]"）も必要です。

Claude Desktop との連携

claude_desktop_config.jsonファイルに次の設定を追加してください。

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      }
    }
  }
}

Cursor との連携

Cursor は stdio 経由で MCP サーバーをサポートしています。次の場所に設定を追加してください。

• グローバル（すべてのプロジェクト）：~/.cursor/mcp.json
• プロジェクトごと（このリポジトリのみ）：.cursor/mcp.json

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      }
    }
  }
}

変更を保存した後、Cursor ウィンドウを再読み込みしてください（Ctrl+Shift+P → ウィンドウを再読み込み）。

Kiro との連携

Kiro は専用の設定ファイルを通じて MCP サーバーをサポートしています。

• グローバル：~/.kiro/settings/mcp.json
• ワークスペース：.kiro/settings/mcp.json

{
  "mcpServers": {
    "ksef-pl": {
      "command": "uvx",
      "args": ["mcp-ksef-pl"],
      "env": {
        "KSEF_ENVIRONMENT": "test",
        "KSEF_SESSION_TOKEN": "<your-ksef-session-token>",
        "KSEF_NIP": "<your-nip>"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

セキュリティ上のヒント：トークンを直接入力する代わりに、 "KSEF_SESSION_TOKEN": "${KSEF_SESSION_TOKEN}"という構文を使用してください。Kiro は起動時にシェルの環境 変数を解決します。

利用可能なツール

FA(3) / FA(2) 請求書の処理

ツール	説明
generate_fa3_invoice	KSeF 準拠の FA(3) XML 請求書を生成します（KSeF API v2 への送信に必要です）
generate_fa2_invoice	KSeF 準拠の FA(2) XML 請求書を生成します（旧形式、読み取り専用で使用）
validate_fa3_invoice	FA(3) XML を検証します：XSD 検証および FA(3) 固有のビジネスルール
validate_fa2_invoice	FA(2) XML を検証します：XSD 検証（スキーマが利用可能な場合）およびビジネスルール
parse_fa2_invoice	FA(2) XML を構造化された辞書に解析します

公式の FA(2) および FA(3) XSD スキーマはパッケージ内（src/mcp_ksef_pl/schemas/）に含まれており、 importlib.resources 経由で自動的に読み込まれます。手動でのダウンロードや設定は 不要です。validate_fa2_invoice と validate_fa3_invoice は、どのインストール環境でも、 最初から完全な XSD 検証を実行します。

KSeF のライフサイクル

ツール	説明
submit_invoice_to_ksef	FA(3) 請求書を KSeF プラットフォームに送信し、参照番号を返します
get_ksef_invoice_status	参照番号を使って請求書の処理状況を取得します
search_ksef_invoices	日付範囲と方向（販売者／購入者）を指定して、KSeF 内の請求書を検索します

識別番号の検証

ツール	説明
validate_polish_nip	チェックサムアルゴリズムを使って、NIP（10 桁の納税者識別番号）を検証します
validate_polish_regon	チェックサムアルゴリズムを使って、REGON（9 桁または 14 桁の登録番号）を検証します

Peppol / EN 16931

ツール	説明
generate_peppol_invoice	Peppol BIS Billing 3.0 / EN 16931 に準拠した UBL 2.1 請求書を生成します
validate_peppol_invoice	CEN EN 16931 基本 Schematron ルール（en16931-base-only スコープ。Peppol 固有のオーバーレイは検証しません）に照らして UBL 2.1 Peppol 請求書を検証します

Peppol ネットワークツール

Peppol 参加者の検索、サービスエンドポイントの検索、DNS のみの診断、AS4 送信、Peppol Directory 検索、および OpenPeppol eDEC コードリストツールは、共有コア Peppol ツールプラグイン（mcp_einvoicing_core.peppol.tools.register_peppol_tools）によって提供されます。これらは、ポーランド固有の識別子アダプターとともに server.py でマウントされます。NIP のみ（例：1234563218）の識別子は 9945:<digits> Peppol スキーム（OpenPeppol eDEC 参加者識別子スキームのコードリストに基づく PL:VAT）に正規化され、すでにスキームが付与された識別子（例：9945:1234563218）はそのまま渡されます。generate_peppol_invoice を使う前に、これらのツールで PEF（公共調達の B2G 請求書向けポーランド Peppol アクセスポイント）の登録状況を確認してください。

peppol_send は、mcp-einvoicing-core v1.20.0 以降、実際の wsse:Security 署名を使って送信メッセージに署名します（以前は署名を計算していましたが、破棄していました。CHANGELOG.md v0.8.0 を参照）。

ツール	説明
peppol_lookup_participant	事業者が Peppol ネットワークに登録されているか確認します。登録状況と対応するドキュメントタイプを返します
peppol_get_service_endpoint	参加者のドキュメントタイプに対応する AS4 エンドポイントを取得します
resolve_peppol_dns	SMP への到達性とは独立した DNS のみ（SML）診断
peppol_send	AS4 経由で UBL/CII 請求書を送信します
peppol_directory_search	参加者、名称、国、またはドキュメントタイプで公開 Peppol Directory を検索します
list_participant_id_schemes, list_document_type_ids, list_process_ids, list_spis_use_case_ids	OpenPeppol eDEC コードリストの検索（EINVOICING_PEPPOL_CODELIST_DIR が必要です）
check_document_type_id_in_codelist, check_process_id_in_codelist, check_participant_id_scheme_in_codelist, get_peppol_codelist_version	OpenPeppol eDEC コードリストの確認とバージョン情報の取得

これらのツールのパラメーターに関する詳細は、mcp-einvoicing-core README を参照してください。

Peppol のレポートとステータス用ツール

v0.8.0 で、オプトイン方式のコアプラグイン 3 つを通じて追加され、server.py で無条件にマウントされます。追加機能またはデータディレクトリがない場合は、登録時ではなく呼び出し時に、明確なエラーが発生します。

ツール	プラグイン	説明
validate_eusr_report	register_peppol_reporting_tools	エンドユーザー統計レポート（XSD、次に Schematron）を検証します。[xslt2] 追加機能が必要です。
validate_tsr_report	register_peppol_reporting_tools	トランザクション統計レポート（XSD、次に Schematron）を検証します。[xslt2] 追加機能が必要です。
validate_mls_message	register_peppol_mls_tools	メッセージレベルステータス文書（UBL ApplicationResponse-2 のサブセット）を検証します。[xslt2] 追加機能が必要です。
build_mls_message	register_peppol_mls_tools	文書レベルの MLS 応答を作成します。[xslt2] 追加機能が必要です。
list_*／check_* のペア 13 組、get_en16931_codelist_version	register_en16931_codelist_tools	EN 16931 の意味コードリストの検索／チェック（単位、VAT カテゴリなど）を行います。EINVOICING_EN16931_CODELIST_DIR が必要です。

これらのツールのパラメーターに関する詳細なドキュメントは、mcp-einvoicing-core の README をご覧ください。

KSeF 認証

KSeF API v2 では、AccessToken を発行するために、複数の手順からなるチャレンジ／引き換えフローを使用します。この MCP サーバーでは取得済みのトークンを受け付けますが、署名手順を自動化することはできません（認定電子署名が必要です）。

手順ごとのフロー

1. アカウントの設定。 KSeF ポータル（https://ksef.mf.gov.pl/）に登録します。対象の環境（テストまたは本番）を選択します。テスト環境は https://ksef-test.mf.gov.pl/ です。

2. チャレンジのリクエスト。 KSeF API を呼び出して、チャレンジを含む XML エンベロープを取得します。

   curl -s https://ksef-test.mf.gov.pl/auth/challenge \
     -H "Accept: application/json" \
     -d '{"contextIdentifier": {"type": "onip", "identifier": "YOUR_NIP"}}' \
     -H "Content-Type: application/json"
   

   応答には challenge 文字列と timestamp が含まれます。

3. チャレンジへの署名。 チャレンジを含む <InitSessionTokenRequest> XML エンベロープを作成し、認定電子署名で署名します。以下の署名ツールが利用できます。

   • 認定電子署名プロバイダー：KIR（Szafir）、Certum、Sigillum
   • podpis.gov.pl（政府の署名ポータル）
   • Profil Zaufany（信頼プロファイル）：https://www.podatki.gov.pl/ksef/

   PKCS#12 証明書と xmlsec1 を使用する例：

   # Build the challenge XML (template at specs/przyklad-wyzwania.xml)
   xmlsec1 --sign --pkcs12 your-cert.p12 --pwd "password" \
     --output signed-challenge.xml challenge-template.xml
   

4. 署名済みチャレンジの送信。 署名済み XML を POST して、authOperation 参照を受け取ります。

   curl -s https://ksef-test.mf.gov.pl/auth/xades-signature \
     -H "Content-Type: application/octet-stream" \
     --data-binary @signed-challenge.xml
   

5. AccessToken の引き換え。 認証済みの操作を AccessToken と交換します。

   curl -s https://ksef-test.mf.gov.pl/auth/token/redeem \
     -H "Content-Type: application/json" \
     -H "Authorization: Bearer <referenceNumber-or-authOperation-token-from-step-4>"
   

   応答には accessToken.token と accessToken.context.referenceNumber が含まれます。

6. トークンの設定。 この MCP サーバー用にトークンをエクスポートします。

   export KSEF_SESSION_TOKEN="<the AccessToken from step 5>"
   

   トークンの有効期間は、発行から約 2 時間です（MF のドキュメントによる）。有効期限が切れたら、手順 2～5 を繰り返します。

参考資料

• KSeF 技術ドキュメント：https://www.podatki.gov.pl/ksef/dokumentacja-techniczna-ksef/
• 認証仕様（CIRFMF）：https://github.com/CIRFMF/ksef-docs/blob/main/uwierzytelnianie.md
• インタラクティブセッション仕様（CIRFMF）：https://github.com/CIRFMF/ksef-docs/blob/main/sesja-interaktywna.md
• FA(3) 移行のお知らせ：specs/ksef-v2-fa3-migration-announcement-20250630.pdf

アーキテクチャ

このサーバーは、AI エージェントと KSeF プラットフォームおよび Peppol ネットワーク間のインテリジェントな通信インターフェイスとして機能します。

[ ERP System / Application ] <--> [ MCP Server ] <--> [ KSeF (MF) / Peppol Network ]
          ^                           |
          |                           v
   [ AI Agent (Claude) ] <--- (FA(2) / EN 16931)

ベンダー中立性

このサーバーは標準自体を実装しており、文書の作成、検証、署名をローカルで行います。商用の請求書プラットフォーム用クライアントではなく、署名キーや認証情報が自社のインフラストラクチャの外に出ることはありません。

請求書は仲介業者を介さず、自社の認証トークンを使って KSeF に直接送信されます。

テスト

# Run unit tests
uv run pytest tests/ -v

貢献

貢献を歓迎します。ガイドラインについては CONTRIBUTING.md をご覧ください。

その他の電子インボイス MCP サーバー

国	サーバー
🌍 グローバル	mcp-einvoicing-core
🇧🇪 ベルギー	mcp-einvoicing-be
🇧🇷 ブラジル	mcp-nfe-br
🇫🇷 フランス	mcp-facture-electronique-fr
🇩🇪 ドイツ	mcp-einvoicing-de
🇮🇳 インド	mcp-einvoicing-in
🇮🇹 イタリア	mcp-fattura-elettronica-it
🇲🇽 メキシコ	mcp-cfdi-mx
🇵🇱 ポーランド	mcp-ksef-pl
🇸🇬 シンガポール	mcp-invoicenow-sg
🇪🇸 スペイン	mcp-facturacion-electronica-es
🇦🇪 アラブ首長国連邦	mcp-einvoicing-ae

ライセンス

このプロジェクトは Apache 2.0 ライセンスの下で配布されています。 詳細については LICENSE ファイルをご覧ください。完全なバージョン履歴については、CHANGELOG.md をご覧ください。