Skip to main content
Glama

PyPI Python CI License Smart Mobile House

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

search_by_nip(nip, date)

Look up a taxpayer by 10-digit NIP (tax id).

search_by_regon(regon, date)

Look up a taxpayer by 9- or 14-digit REGON.

search_by_bank_account(bank_account, date)

Find taxpayers associated with an account.

search_bulk(identifiers, id_type, date)

Look up 1–30 identifiers of one type in a single API request.

check_bank_account(identifier, id_type, bank_account, date)

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-mcp

By 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 / NIE as returned

  • Local NIP, REGON and bank-account checksum validation

  • A source block with the register, environment and UTC retrieval time in every response

  • Runs on the sandbox with no key; live data with VAT_ENV=prod

  • Released through GitHub Actions with PyPI Trusted Publishing and MCP Registry metadata

Configuration

Variable

Default

Description

VAT_ENV

test

test for the sandbox or prod for live data.

VAT_TIMEOUT

30

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 network

The 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

vat-whitelist-mcp

GitHub owner

SmartMobileHouse

Repository

vat-whitelist-mcp

Workflow filename

publish.yml

Environment

pypi

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=prod for 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-DD dates 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 tools
check_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

    A3.5/5.0

    Scored across 5 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Look 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.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      2
      9 npm
      MIT