Skip to main content
Glama
bartosz-kuc

honest-vies-mcp

by bartosz-kuc
OverviewSchemaRelated ServersScoreDiscussions
Python

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.

Related MCP server: euinvoice-mcp

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.

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

Available Tools

2 tools
check_vatA

Check an EU VAT number against the VIES database (the EU-wide cross-border VAT validator). Returns valid/invalid + registered name and address if the national database returns them. Accepts either (country_code, vat_number) separately or a combined vat like 'PL5252344078'. For Polish JDG issuing 0% VAT invoices to EU B2B customers: ALSO pass requester_country + requester_vat with your own PL VAT — VIES will return a consultation_number that serves as legal proof of the check. Keep this number for your records. VIES will not issue a consultation number if EITHER VAT is invalid.

ParametersJSON Schema
NameRequiredDescriptionDefault
vatNoAlternative: combined form like 'PL5252344078'. If provided, country_code and vat_number are ignored.
vat_numberNoVAT number without country prefix. Dashes/spaces will be stripped.
country_codeNo2-letter EU country code (e.g., PL, DE, FR). Greece uses EL, not GR. XI is Northern Ireland.
requester_vatNoOptional: your own VAT number without country prefix. Combined with requester_country to obtain a consultation number as legal proof of the check.
requester_countryNoOptional: your own 2-letter country code (e.g., PL). Required together with requester_vat to obtain a consultation number.

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It explains the return behavior (valid/invalid, name/address if available), the combined vs. separate input forms, and the special consultation number mechanism for Polish JDG. It also warns about when VIES will not issue a consultation number, which is a critical behavioral nuance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is moderately long but each sentence contributes information. It front-loads the core purpose and return value, then details the input forms and the special case. There is no filler or repetition, though it could be slightly trimmed without losing critical detail.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (5 parameters, two input modes, optional requester fields, a special legal-proof mechanism), the description covers all necessary aspects: input variants, return format, and the condition for obtaining a consultation number. Without an output schema, the description adequately explains what the agent can expect from the call.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema: it explains the relationship between requester_country and requester_vat, emphasizes the combined 'vat' parameter's precedence, and provides the Greek/Northern Ireland country code exceptions. This exceeds the baseline by adding practical usage semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: checking an EU VAT number against the VIES database. It specifies the verb 'Check', the resource (EU VAT number), and the validation scope (VIES). It also distinguishes itself from the sibling tool (list_supported_countries) by focusing on validation rather than listing countries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context on when to use the tool (to check VAT numbers) and even includes a specific use case (Polish JDG issuing 0% VAT invoices). However, it does not explicitly discuss alternatives or exclusions relative to list_supported_countries, though the purpose difference is implicit. Missing a direct 'when not to use' guidance, but the context is sufficient.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_supported_countriesA

List the country codes supported by VIES (all 27 EU member states, plus XI for Northern Ireland).

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden. It clearly describes a read-only listing operation with no side effects, and specifies the exact set of codes. It doesn't state the return format, but for a zero-parameter list tool the implication of returning an array of strings is strong enough. Slight gap in not explicitly stating it is safe/read-only, but it is entirely inferred from the verb 'List'.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence front-loads the action, resource, and scope without any wasted words. Every element ('List', 'country codes', 'VIES', the list of codes) earns its place. No redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, no-output-schema tool, this description is complete. It tells the agent exactly what the tool returns (the set of supported codes) and the extent of that set. There is nothing an agent needs to know to call it correctly that is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, so the baseline per rubric is 4. The description adds no parameter information because none is needed; the tool takes no input and simply returns a static list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb ('List'), a specific resource ('country codes supported by VIES'), and the exact scope (27 EU member states plus XI). This unambiguously distinguishes it from the sibling check_vat, which performs a different operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Although it doesn't explicitly name check_vat, the purpose is self-evident: use this tool when you need the set of supported country codes. There is no alternative for listing countries, so no exclusion is needed. The context makes the appropriate usage clear without ambiguity.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updatesv0.1.0
    • First observedcheck_vat
    • First observedlist_supported_countries
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.7/5.0
Disambiguation5/5

The two tools have clearly distinct purposes: one validates a VAT number, the other lists supported country codes. There is no overlap or ambiguity in their functionality.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (check_vat, list_supported_countries). The naming is predictable and uniform.

Tool Count4/5

With only two tools, the server is minimal but appropriately scoped for its narrow purpose of VIES VAT validation. It is slightly thin but each tool earns its place, so it is reasonable.

Completeness5/5

The tool surface fully covers the domain: checking VAT numbers (with optional consultation number for legal proof) and listing supported countries. No obvious gaps exist for the intended use case.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • vatnode by vatnode

    vatnodeofficial

    vatnode
    A
    license
    A
    quality
    B
    maintenance
    Official MCP server: EU VAT validation via VIES, plus offline rates and format checks.
    5
    80
    1
    MIT

  • euinvoice-mcp

    artisan-at-work
    A
    license
    Not graded
    quality
    F
    maintenance
    An MCP server for European invoicing rules. Query VAT rates, e-invoicing requirements, format specifications, and compliance rules for EU-27 + EEA countries.
    24
    MIT

  • @m8t-jacob/mcp-polish-biz

    M8T-Jacob
    A
    license
    A
    quality
    C
    maintenance
    MCP server that provides AI agents with Polish business data tools: identifier validation (NIP, PESEL, REGON, KRS, IBAN), VAT whitelist checks, EU VIES lookups, and NBP exchange rates.
    5
    21
    MIT

  • vies-smoother

    Lucrumist
    A
    license
    Not graded
    quality
    C
    maintenance
    SLA'd EU VAT number validation for AI agents via VIES, with caching and circuit-breaking to handle flaky upstream, returning valid/invalid/unavailable responses.
    MIT

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/bartosz-kuc/honest-vies-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server