VAT White List (Poland)

vat-whitelist-mcp

一个 Model Context Protocol 服务，为 AI 助手提供对波兰 VAT 白名单（Wykaz podatników VAT）的清晰、类型化访问。可按 NIP、REGON 或银行账户查询纳税人，并验证某个账户在指定日期是否关联有效纳税人。

官方 VAT 白名单 API 会返回纳税人详情、VAT 状态、银行账户和确认标识符。vat-whitelist-mcp 将其 REST 搜索和核验方法封装为五个简单工具。

由 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)	在一次 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 和一个 source 区块，其中注明登记册、环境以及 UTC 格式的 retrieved_at 时间。API 的 requestId 和 requestDateTime 会保留，原始纳税人字段也会一并返回。

批量查询的 id_type 为 nip、regon 或 bank_account；账户核验的 id_type 为 nip 或 regon。批量查询的 results 中每个标识符对应一条记录，记录包含 subjects 或上游 error；count 统计记录数。requested 包含规范化后的输入，unmatched 列出查询成功但没有匹配到任何纳税人的记录。失败的记录绝不会被当作缺失纳税人处理。核验结果会保留 accountAssigned 的 TAK 或 NIE 值；API 失败时会引发错误，而不是返回 NIE。

快速开始

无需安装 — 使用 uv 直接从仓库运行：

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

默认使用 sandbox，无需 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 表示 sandbox，使用 prod 表示实时数据。
VAT_TIMEOUT	30	以秒为单位的正有限 HTTP 超时时间。

可在 shell 或 MCP 配置中设置这些变量。.env.example 是参考文件；不会自动加载 .env 文件。

sandbox 的 API 基础 URL 为 https://wykazpodatnikowvat-test.mf.gov.pl/api/，生产环境的 API 基础 URL 为 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 可能会对历史数据施加其他限制。
• 公布的限额为每天 100 次搜索请求、每次请求最多 30 个标识符，以及每天 5,000 次查验验证。配额按请求 IP 计算；配额用尽后，访问可能会被阻止，直到午夜。请参阅 官方 API 文档 了解当前条款和限额。
• WL2 状态查询和扁平文件验证不在此工具集的范围内。
• 本项目独立运营，与财政部或国家税务管理局无关联，也未获其认可。

许可证

MIT © Smart Mobile House