VIES VAT Validator MCP

VIES VAT Validator MCP 🇪🇺

VIES VAT Validator MCP validates EU VAT numbers through the official free VIES SOAP API, wrapped with a local format pre-check + free TTL cache and bilingual (中文 / English) error codes. A "regulatory must-have" compliance tool for cross-border e-commerce and trade sellers.

Current version: 1.0.3 · License: MIT · Trust: built read-only, no secret exfiltration, self-healing bilingual errors.

EN — Two-stage EU VAT validation: free offline format pre-check, then live VIES, with bilingual error codes.

简体中文 — 两段式欧盟 VAT 校验：本地免费格式预检 + 官方 VIES 实查，中英双语错误码。

繁體中文 — 兩段式歐盟 VAT 校驗：本地免費格式預檢 + 官方 VIES 實查，中英雙語錯誤碼。

🌐 [English](#english) · [简体中文](#简体中文) · [繁體中文](#繁體中文)

---

English

Why this exists

• Regulatory must-have — EU B2B transactions require verifying the counterparty's VAT number (reverse charge / compliance proof).
• VIES is slow and flaky — the official SOAP endpoint rate-limits and goes down often, so a cache + graceful degradation are mandatory.
• Zero cold-start cost — a free official data source wrapped with a thin layer + bilingual, explainable output, sold per-event.

What you get

Covers EU 27 + GB + XI (Northern Ireland). Every country also carries its native name and — far more useful — the local term for the VAT number, which is what people actually search for:

叫法取当地商务常用写法；部分国家有不止一种官方接受的写法，表中列最主要的那种。

Terms follow common local business usage — some countries accept more than one form; the main one is shown.

Quick start (local)

npm install

npm run build npm start # stdio transport, connects to any MCP client npm test # vitest, all green npm run verify # generate verify-report.html with real payloads

Connect with an MCP client (stdio)

{

"mcpServers": { "vat-validator": { "command": "node", "args": ["/abs/path/vies-vat-validator-mcp/dist/index.js"] } } }

Connect over HTTP (remote / Apify)

Point your MCP client at the Streamable HTTP endpoint:

https://neeenja--vies-vat-validator-mcp.apify.actor/mcp

with the header Authorization: Bearer .

Example calls

Format pre-check (free)

{ "name": "check_vat_format", "arguments": { "vat": "FR123456789" } }

→ { "formatValid": true, "normalized": "FR123456789", "pattern": "^([A-Z]{2})?\\d{9}$" }

Live verification (paid event)

{ "name": "validate_vat", "arguments": { "vat": "FR123456789", "useCache": true, "live": true } }

→ { "valid": true, "formatValid": true, "viesValid": true, "source": "vies", "name": "...", "address": "..." }

Error codes (excerpt)

Full table via get_error_codes or vat://error-codes.

Deploy (Apify Pay-Per-Event)

npm run apify:login      # complete KYC yourself first (one-time)

npm run apify:validate # validate actor.json npm run apify:push # publish to Apify Store

Pricing lives in .actor/actor.json → pricingEvents: format / error / country queries are free; only mcp-validate-vat is billed.

Design red lines

• No express / soap / fast-xml-parser: the SOAP envelope is hand-built and the response parsed with namespace-agnostic regex.
• Never crash: VIES faults / network errors map to bilingual error codes.
• Free layer (format check + cache) guarantees zero cold-start cost.

See SPEC.md for the full contract.

---

简体中文

为什么做这个

• 监管刚需 —— 欧盟 B2B 交易要求核验对方 VAT 税号（逆向征收 / 合规凭证）。
• VIES 又慢又抖 —— 官方 SOAP 接口频繁限流、偶发停机，缓存 + 优雅降级是必选项。
• 零冷启动成本 —— 免费官方数据源，叠加一层封装 + 可解释的双语输出，按事件计费。

你能拿到什么

覆盖 EU 27 + GB + XI（北爱尔兰）。每个国家还带母语名，以及更实用的当地对 VAT 号的叫法——这才是当地人真正会搜的词：

叫法取当地商务常用写法；部分国家有不止一种官方接受的写法，表中列最主要的那种。

Terms follow common local business usage — some countries accept more than one form; the main one is shown.

快速开始（本地）

npm install

npm run build npm start # stdio 传输，接任意 MCP 客户端 npm test # vitest 全绿 npm run verify # 生成真实 payload 验证报告 verify-report.html

与 MCP 客户端对接（stdio）

{

"mcpServers": { "vat-validator": { "command": "node", "args": ["/abs/path/vies-vat-validator-mcp/dist/index.js"] } } }

通过 HTTP 对接（远程 / Apify）

把你的 MCP 客户端指向 Streamable HTTP 端点：

https://neeenja--vies-vat-validator-mcp.apify.actor/mcp

并带上请求头 Authorization: Bearer 。

调用示例

格式预校验（免费）

{ "name": "check_vat_format", "arguments": { "vat": "FR123456789" } }

→ { "formatValid": true, "normalized": "FR123456789", "pattern": "^([A-Z]{2})?\\d{9}$" }

实查（付费事件）

{ "name": "validate_vat", "arguments": { "vat": "FR123456789", "useCache": true, "live": true } }

→ { "valid": true, "formatValid": true, "viesValid": true, "source": "vies", "name": "...", "address": "..." }

错误码（节选）

完整表见 get_error_codes 或 vat://error-codes。

部署（Apify Pay-Per-Event）

npm run apify:login      # 本人先完成 KYC（一次性）

npm run apify:validate # 校验 actor.json npm run apify:push # 上架

计费见 .actor/actor.json 的 pricingEvents：格式 / 错误 / 国家查询免费，仅 mcp-validate-vat 计费。

设计红线

• 不引入 express / soap / fast-xml-parser：SOAP 信封手写、响应用命名空间无关的正则提取。
• 永不崩溃：VIES 故障 / 网络错误全部映射为双语错误码。
• 免费层（格式校验 + 缓存）保证冷启动零成本。

完整契约见 SPEC.md。

---

繁體中文

為什麼做這個

• 監管剛需 —— 歐盟 B2B 交易要求核驗對方 VAT 稅號（逆向徵收 / 合規憑證）。
• VIES 又慢又抖 —— 官方 SOAP 介面頻繁限流、偶發停機，快取 + 優雅降級是必選項。
• 零冷啟動成本 —— 免費官方資料源，疊加一層封裝 + 可解釋的雙語輸出，按事件計費。

你能拿到什麼

涵蓋 EU 27 + GB + XI（北愛爾蘭）。每個國家還帶母語名，以及更實用的當地對 VAT 號的叫法——這才是當地人真正會搜的詞：

| BG | България | ДДС номер | 保加利亚 | Bu