honest-vies-mcp

Local MCP server for the EU VIES VAT number validator (the authoritative EU-wide check used before issuing 0% VAT cross-border invoices) — no authentication, no rate limit, no cloud middle.

Part of the honest-mcp family of small, auditable, local-first MCP servers.

Why

A Polish JDG (or any EU business) issuing a 0% VAT reverse-charge invoice to an EU B2B customer must first verify that customer's VAT number is registered in VIES — and keep evidence of the check. Skipping this and it turns out the customer's VAT is invalid, the Polish tax office will demand 23% VAT from you, retroactively, plus interest.

This server puts VIES a single tool call away. Ask your AI "verify DE143454214 before I issue this invoice" and you get: valid/invalid, registered name and address, and a consultation number for your records if you provided your own VAT.

Same trust model as the rest of the family: data flows only between your machine and the European Commission.

Features

Two tools:

• check_vat — validate a single EU VAT number. Optionally pass your own VAT (requester_country + requester_vat) to receive a consultation number as legal proof of the check.
• list_supported_countries — the 27 EU country codes + XI for Northern Ireland.

Data source

• Endpoint: ec.europa.eu/taxation_customs/vies/ REST API
• No API key, no registration
• Coverage: 27 EU member states + Northern Ireland (XI)
• Note: Greece uses country code EL, not GR

Requirements

• Python 3.10+

Setup

git clone https://github.com/bartosz-kuc/honest-vies-mcp.git
cd honest-vies-mcp
python3 -m venv venv
./venv/bin/pip install -r requirements.txt

Register with Claude Code:

claude mcp add vies /absolute/path/to/venv/bin/python /absolute/path/to/server.py

Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "vies": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/server.py"]
    }
  }
}

Example usage

"Verify German VAT DE143454214 before I invoice them."

check_vat(country_code="DE", vat_number="143454214") → valid/invalid + name/address.

"Verify the same, but also get a consultation number — my VAT is PL7393933151."

check_vat(vat="DE143454214", requester_country="PL", requester_vat="7393933151") → response includes a consultation_number field. Save that number with the invoice.

"What's the EU VAT country code for Greece again?"

list_supported_countries() → confirms Greece is EL, not GR.

Data flow

Your AI client
     ↕  MCP stdio
This server (Python, on your machine)
     ↕  HTTPS
ec.europa.eu (VIES)

No cloud middle. Nothing to log in to. No telemetry.

For Polish JDG owners

The tax law bit: art. 42 ust. 1 pkt 1 ustawy o VAT — before applying the 0% rate on an intra-community supply (WDT), the seller must have a valid VAT-UE number of the buyer. Art. 100 ust. 8 pkt 1 — proof of the check is expected on audit. The consultation_number (VIES's requestIdentifier) is the standard evidence: it's a unique code tying your check to a specific date and pair of VAT numbers. Store it with the invoice.

Non-obvious bits VIES will bite you with:

• If your OWN VAT (the requester) is not currently active in VIES, no consultation number is returned even when the checked VAT is valid.
• VIES is an EU-wide switch — validation happens against the national database of the country in the VAT prefix. Occasionally a national database is offline; the server surfaces that clearly instead of pretending it's a valid/invalid result.

Author

Bartosz Kuć — Warsaw-based developer, JDG owner running skanfirmy.pl.

• GitHub: https://github.com/bartosz-kuc

• Email: firma@bartosza.pl

Consulting

Available for consulting on Polish tax and business integrations (KSeF, GUS/NFZ/GIOŚ APIs, mBank data), MCP server design, and AI-assisted tooling for JDGs and small teams. See skanfirmy.pl/uslugi for productized packages (audit 3k PLN, setup 8-15k PLN, retainer 2-4k PLN/mo), or reach out via email.

License

MIT — see LICENSE.

Related

• honest-gmail-mcp — local Gmail MCP
• honest-calendar-mcp — local Google Calendar MCP
• honest-drive-mcp — local Google Drive MCP with permission management
• ksef-mcp — Polish KSeF (e-invoicing) MCP
• nip-krs-mcp — Polish company registry MCP (biała lista + KRS)
• nbp-mcp — NBP MCP: exchange rates + gold fixing for Polish accounting