VAT White List (Poland)

vat-whitelist-mcp

AI アシスタントがポーランドの VAT ホワイトリスト（Wykaz podatników VAT）に、整然とした型付きアクセスを行えるようにする Model Context Protocol サーバーです。NIP、 REGON、または銀行口座で納税者を検索し、指定した日に口座が有効な納税者に紐付いているかどうかを確認できます。

公式の VAT White List API は、納税者の詳細、VAT のステータス、銀行口座、確認識別子を返します。 vat-whitelist-mcp は、その REST 検索メソッドと照合メソッドを、シンプルな 5 つのツールとして公開します。

Smart Mobile House が開発・保守しています — エンタープライズ向けのセキュアな AI 実装です。

ツール

ツール	説明
search_by_nip(nip, date)	10 桁の NIP（納税者番号）で納税者を検索します。
search_by_regon(regon, date)	9 桁または 14 桁の REGON で納税者を検索します。
search_by_bank_account(bank_account, date)	口座に紐付いている納税者を検索します。
search_bulk(identifiers, id_type, date)	1 回の API リクエストで、同じ種類の識別子を 1～30 件検索します。
check_bank_account(identifier, id_type, bank_account, date)	NIP または REGON で、有効な納税者に口座が紐付いているか確認します。

すべてのツールで、YYYY-MM-DD 形式の日付を明示的に指定する必要があります。NIP、REGON、ポーランドの銀行口座番号のチェックサムはローカルで検証されます。銀行口座番号には、26 桁の NRB または PL 形式の IBAN を指定でき、一般的な区切り文字も使用できます。

検索レスポンスには、count、results、date、およびレジスター、環境、UTC の retrieved_at 時刻を示す source ブロックが含まれます。API の requestId と requestDateTime は保持され、元の納税者フィールドも含まれます。

一括検索の id_type は nip、regon、または bank_account です。照合の id_type は nip または regon です。一括検索の results には、識別子ごとに 1 件のエントリーが含まれ、それぞれ subjects または上流 API の error のいずれかを含みます。count はエントリー数です。requested には正規化された入力が含まれ、unmatched には subjects が見つからなかった成功済みエントリーが列挙されます。失敗したエントリーを、納税者が存在しないものとして扱うことはありません。照合では accountAssigned が TAK または NIE のまま保持されます。API エラーが発生した場合は、NIE を返すのではなくエラーを発生させます。

クイックスタート

インストールは不要です。uv を使って、リポジトリから直接実行できます。

uvx --from git+https://github.com/SmartMobileHouse/vat-whitelist-mcp vat-whitelist-mcp

デフォルトではサンドボックスを使用するため、API キーやアカウントは不要です。本番データを使用するには、VAT_ENV=prod を設定します。たとえば、アシスタントに今日の日付を明示して NIP を検索するよう依頼します。

PyPI での初回リリース後は、uvx vat-whitelist-mcp としても実行できます。

Claude Desktop / Claude Code での使用

MCP 設定に追加します（例：claude_desktop_config.json または .mcp.json）。

{
  "mcpServers": {
    "vat-whitelist": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/SmartMobileHouse/vat-whitelist-mcp", "vat-whitelist-mcp"],
      "env": {
        "VAT_ENV": "prod"
      }
    }
  }
}

開発中は、代わりにローカルのチェックアウト先を指定します。

{
  "mcpServers": {
    "vat-whitelist": {
      "command": "uvx",
      "args": ["--from", "/absolute/path/to/vat-whitelist-mcp", "vat-whitelist-mcp"],
      "env": { "VAT_ENV": "test" }
    }
  }
}

設定

変数	デフォルト	説明
VAT_ENV	test	サンドボックスには test、本番データには prod を指定します。
VAT_TIMEOUT	30	HTTP タイムアウト（秒）。正の有限値を指定します。

これらの値は、シェルまたは MCP の設定で指定します。.env.example は参考用です。 .env ファイルは自動的には読み込まれません。

API のベース URL は、サンドボックスでは https://wykazpodatnikowvat-test.mf.gov.pl/api/、本番環境では https://wykazpodatnikowvat.mf.gov.pl/api/ です。

開発

git clone https://github.com/SmartMobileHouse/vat-whitelist-mcp
cd vat-whitelist-mcp
uv sync --locked        # create the venv and install dependencies
uv run pytest           # offline validation, mocked HTTP, MCP discovery and stdio tests
                        # (network tests are skipped by default)
uv run vat-whitelist-mcp # run the server over stdio
uv build                # build source and wheel distributions
uvx twine check dist/*  # validate package metadata

# Live tests against the official sandbox (opt-in; no production requests):
VAT_RUN_NETWORK=1 uv run pytest -m network

クライアントは httpx を使用する小規模な REST レイヤーです（ src/vat_whitelist_mcp/client.py を参照）。認証セッションや自動リトライはありません。Python 3.10 以降が必要です。

リリース

GitHub Actions は、プルリクエストと main へのプッシュ時にオフラインテストを実行し、バージョンを検証し、wheel とソース配布物をビルドして、メタデータを確認します。 v0.1.0 のようなバージョンタグをプッシュすると、Trusted Publishing を使用してテスト済みの成果物が PyPI に公開され、その後、対応する MCP Registry のメタデータが公開されます。 このワークフローは、main から手動で実行することもできます。

初回リリースの前に、メンテナーの PyPI アカウントで、次の値を設定した保留中の Trusted Publisherを追加してください。

フィールド	値
PyPI プロジェクト名	vat-whitelist-mcp
GitHub オーナー	SmartMobileHouse
リポジトリ	vat-whitelist-mcp
ワークフローファイル名	publish.yml
環境	pypi

GitHub の pypi 環境が存在している必要があります。PyPI API トークンは不要です。PyPI の設定ガイドを参照してください。 タグ付けの前に、pyproject.toml、src/vat_whitelist_mcp/__init__.py、server.json のバージョンを一致させてください。PyPI への公開成功後に MCP Registry のジョブが失敗した場合は、独立して再実行できます。

注意事項と制限

• サンドボックスのデータは合成データです。実際の納税者情報には VAT_ENV=prod を使用してください。
• 日付はポーランドの今日以前で、現在の暦年または過去5暦年以内、かつ2019年9月1日以降である必要があります。 API によっては、過去のデータに追加の制限が課される場合があります。
• 公開されている制限は、1日あたり100件の検索リクエスト、1リクエストあたり最大30件の識別子、1日あたり5,000件の確認照会です。クォータはリクエスト元のIPに適用され、クォータを使い切ると、午前0時までアクセスがブロックされる場合があります。 最新の利用条件と制限については、公式APIドキュメントを参照してください。
• WL2 のステータス照会とフラットファイル検証は、このツールセットの対象外です。
• このプロジェクトは独立しており、財務省または国家歳入庁との提携関係や、これらの機関による推奨はありません。

ライセンス

MIT © Smart Mobile House