vat-whitelist-mcp
This MCP server provides typed tools to query the Polish VAT White List and verify bank account associations.
Search taxpayer details by 10-digit NIP on an explicit YYYY-MM-DD date.
Search taxpayer details by 9- or 14-digit REGON.
Find taxpayers associated with a Polish bank account, accepting 26-digit NRB or PL IBAN.
Bulk-search 1–30 identifiers of one type: nip, regon, or bank_account.
Check whether a bank account is assigned to an active taxpayer identified by NIP or REGON, preserving TAK/NIE.
Locally validate NIP, REGON, and bank-account checksums before requests; responses retain date, source, request IDs, and retrieval metadata.
Run against the sandbox by default or production data with VAT_ENV=prod.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@vat-whitelist-mcp check if account PL61109010140000071219812874 belongs to NIP 5261040828 on 2025-06-01"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
What it does
A Model Context Protocol server that gives AI assistants clean, typed access to the Polish VAT White List (Wykaz podatników VAT). Look up taxpayers by NIP, REGON, or bank account and verify whether an account is associated with an active taxpayer on a specified date.
The official VAT White List API
returns taxpayer details, VAT status, bank accounts, and confirmation identifiers.
vat-whitelist-mcp exposes its REST search and check methods as five simple tools.
Tool | Description |
| Look up a taxpayer by 10-digit NIP (tax id). |
| Look up a taxpayer by 9- or 14-digit REGON. |
| Find taxpayers associated with an account. |
| Look up 1–30 identifiers of one type in a single API request. |
| Check an account's association with an active taxpayer by NIP or REGON. |
Every tool requires an explicit YYYY-MM-DD date. NIP, REGON, and Polish bank
account checksums are validated locally. Bank accounts accept a 26-digit NRB or
its PL IBAN form, with common grouping separators.
Search responses contain count, results, date, and a source block naming
the register, environment, and UTC retrieved_at time. The API's requestId and
requestDateTime are retained, along with the original taxpayer fields.
Bulk id_type is nip, regon, or bank_account; check id_type is nip or
regon. Bulk results contain one entry per identifier, with either subjects
or an upstream error; count counts entries. requested contains normalized
inputs, and unmatched lists successful entries with no subjects. Failed entries
are never treated as missing taxpayers. Checks preserve accountAssigned as
TAK or NIE; API failures raise errors rather than returning NIE.
Design notes: the vat-whitelist-mcp write-up.
Related MCP server: nip-checker-mcp
Quick start
No install needed — run it straight from the repo with uv:
uvx --from git+https://github.com/SmartMobileHouse/vat-whitelist-mcp vat-whitelist-mcpBy default it uses the sandbox, with no API key or account required. Set
VAT_ENV=prod for live data. For example, ask your assistant to look up a NIP
using today's explicit date.
It is also published on PyPI, so uvx vat-whitelist-mcp works too.
Use it in Claude Desktop / Claude Code
Add to your MCP config (e.g. claude_desktop_config.json or .mcp.json):
{
"mcpServers": {
"vat-whitelist": {
"command": "uvx",
"args": ["--from", "git+https://github.com/SmartMobileHouse/vat-whitelist-mcp", "vat-whitelist-mcp"],
"env": {
"VAT_ENV": "prod"
}
}
}
}During development, point it at a local checkout instead:
{
"mcpServers": {
"vat-whitelist": {
"command": "uvx",
"args": ["--from", "/absolute/path/to/vat-whitelist-mcp", "vat-whitelist-mcp"],
"env": { "VAT_ENV": "test" }
}
}
}Status
Search by NIP, REGON and bank account
Bulk search of 1–30 identifiers of one type in a single request
Account check against an active taxpayer by NIP or REGON, keeping
TAK/NIEas returnedLocal NIP, REGON and bank-account checksum validation
A
sourceblock with the register, environment and UTC retrieval time in every responseRuns on the sandbox with no key; live data with
VAT_ENV=prodReleased through GitHub Actions with PyPI Trusted Publishing and MCP Registry metadata
Configuration
Variable | Default | Description |
|
|
|
|
| Positive finite HTTP timeout in seconds. |
Set these in the shell or MCP configuration. .env.example is a reference;
.env files are not loaded automatically.
The API base URLs are https://wykazpodatnikowvat-test.mf.gov.pl/api/ for the
sandbox and https://wykazpodatnikowvat.mf.gov.pl/api/ for production.
Development
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 networkThe client is a small REST layer over httpx (see
src/vat_whitelist_mcp/client.py), with no authentication session or automatic
retries. Python 3.10 or newer is required.
Releases
GitHub Actions runs the offline tests, validates versions, builds the wheel and
source distribution, and checks metadata on pull requests and pushes to main.
Pushing a version tag such as v0.1.0 publishes the tested artifacts to PyPI
using Trusted Publishing, then publishes the matching MCP Registry metadata.
The workflow can also be dispatched manually from main.
Before the first release, add a pending Trusted Publisher in the maintainer's PyPI account with these values:
Field | Value |
PyPI project name |
|
GitHub owner |
|
Repository |
|
Workflow filename |
|
Environment |
|
The GitHub pypi environment must exist. No PyPI API token is needed. See
PyPI's setup guide.
Keep versions in pyproject.toml, src/vat_whitelist_mcp/__init__.py, and
server.json aligned before tagging. A failed MCP Registry job can be retried
independently after PyPI succeeds.
Notes & limitations
Sandbox data is synthetic. Use
VAT_ENV=prodfor live taxpayer information.Dates must be no later than today in Poland and fall within the current year or the five preceding calendar years, no earlier than 1 September 2019. The API may impose additional historical-data restrictions.
The published limits are 100 search requests per day, up to 30 identifiers per request, and 5,000 check verifications per day. Quotas apply to the requesting IP; exhausting a quota can block access until midnight. See the official API documentation for current terms and limits.
WL2 status queries and flat-file verification are outside this tool set.
This project is independent and is not affiliated with or endorsed by the Ministry of Finance or the National Revenue Administration.
Contributing
Issues and pull requests are welcome.
Why vat-whitelist-mcp?
Checks need a date and an audit trail
The official VAT White List API answers for a specific date, and every check should show where and when the data came from.
Raw API calls leave the details to every integration
Identifier formats and checksums are easy to get wrong.
API failures must not be mistaken for a missing taxpayer.
This server keeps the checks strict
Explicit
YYYY-MM-DDdates on every tool.Checksums validated locally before any request.
API failures raise errors instead of returning
NIE; request ids and timestamps are kept.
License
MIT © Smart Mobile House. Built and maintained by Smart Mobile House.
Available Tools
5 toolscheck_bank_accountB
Check account association with an active taxpayer on YYYY-MM-DD.
id_type: nip or regon. accountAssigned is the API's TAK/NIE answer; API
failures raise errors and must never be interpreted as a negative match.
Inputs: date (required), id_type (required), identifier (required), bank_account (required).
search_bulkA
Look up 1–30 identifiers in one request on YYYY-MM-DD.
id_type: nip, regon, or bank_account. Results retain each identifier's
subjects or API error. Only successful empty entries appear in unmatched.
count is the number of returned entries, not the number of taxpayers.
Inputs: date (required), id_type (required), identifiers (required).
search_by_bank_accountB
Find taxpayers for a Polish bank account on YYYY-MM-DD; accepts NRB or PL IBAN.
Inputs: date (required), bank_account (required).
search_by_nipC
Look up taxpayer details by NIP on an explicit YYYY-MM-DD date.
Inputs: nip (required), date (required).
search_by_regonC
Look up taxpayer details by 9- or 14-digit REGON on YYYY-MM-DD.
Inputs: date (required), regon (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
The single-identifier lookup tools are clearly separated by NIP, REGON, and bank account, and search_bulk is explicitly bulk. check_bank_account and search_by_bank_account both concern bank-account relationships and could be momentarily confused, but their descriptions distinguish search from association checking.
All tool names use snake_case and clear action/resource wording. There is a minor deviation between search_by_* tools, search_bulk, and check_bank_account, but the pattern remains readable and predictable.
Five tools is well scoped for a focused VAT whitelist lookup server. Each tool covers a distinct lookup mode and none feels redundant or excessive.
The tool set covers core lookup workflows: NIP, REGON, bank account, bulk lookup, and bank-account association checking. Minor gaps exist, such as no dedicated explicit VAT-status check by NIP/REGON beyond search results, but the main domain surface is covered.
Maintenance
Related MCP Connectors
Validate EU, UK, AU VAT numbers for AI agents. EU ViDA e-invoicing compliance.
Verify Polish companies: VAT white list (MF), KRS, VIES, payment audit PDF, monitoring.
Verify Polish companies by NIP/KRS/REGON + EU VAT (VIES). 14 MCP tools (9 no-key).
Polish companies and people: KRS, CEIDG, financials, boards, VAT, sanctions. Free, no API key.
Related MCP Servers
- AlicenseAqualityCmaintenanceLook up Polish companies from any AI assistant: registry data (KRS, REGON, CEIDG), VAT white list checks before payments, and financial statements of 4.4M businesses. Read-only tools backed by official public registers.4MIT
- AlicenseAqualityDmaintenanceEnables real-time verification of Polish NIP (Tax Identification Numbers) using the official Ministry of Finance API. Also supports checking if a bank account belongs to a specific NIP.29 npmMIT
- AlicenseAqualityDmaintenanceProvides AI agents with real-time access to Polish official data: VAT whitelist for company verification and NBP exchange rates, enabling checks on VAT status, company details, and currency conversion without API keys.5MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to verify Polish companies and EU VAT numbers against official government registries using 9 tools, with no API key and optional plain REST access.MIT