VIES VAT Validator MCP

VIES VAT Validator MCP 🇪🇺

VIES VAT Validator MCP 通过官方免费的 VIES SOAP API 校验欧盟 VAT 号码，并结合本地格式预检 + 免费 TTL 缓存以及中英双语错误码。这是面向跨境电商和贸易卖家的「监管合规必备」工具。

当前版本：1.0.3 · 许可证： MIT · 可信保障： 采用只读设计，不会外泄机密，并提供可自我修复的双语错误信息。

EN — 两阶段欧盟 VAT 校验：免费离线格式预检，然后实时查询 VIES，并提供双语错误码。 简体中文 — 两段式欧盟 VAT 校验：本地免费格式预检 + 官方 VIES 实查，中英双语错误码。 繁體中文 — 兩段式歐盟 VAT 校驗：本地免費格式預檢 + 官方 VIES 實查，中英雙語錯誤碼。

🌐 英语 · 简体中文 · 繁體中文

所在位置	链接
MCP 端点	https://neeenja--vies-vat-validator-mcp.apify.actor/mcp
Apify Store	https://apify.com/neeenja/vies-vat-validator-mcp
源代码	https://github.com/PanStories/vies-vat-validator-mcp
收录于	Sartbot 精选

---

英文

为什么开发此工具

• 监管合规必备 — 欧盟 B2B 交易要求验证交易对方的 VAT 号码（反向征税 / 合规证明）。
• VIES 响应缓慢且不稳定 — 官方 SOAP 端点会限制请求频率，也经常宕机，因此缓存和优雅降级必不可少。
• 冷启动成本为零 — 基于免费的官方数据源，仅添加轻量封装，提供双语且易于理解的输出，并按事件计费。

您将获得什么

功能	说明	定价
validate_vat	免费本地格式检查，然后可选实时 VIES 验证；提供结构化双语错误	$0.0005 / 次事件（→ 2026-11-06 起为 $0.005）
check_vat_format	纯本地正则格式检查 — 不联网，免费	免费
list_supported_countries	支持的国家/地区 — 母语名称 + 当地 VAT 叫法 + 中文/EN	免费
get_error_codes	完整的双语错误代码表	免费
资源	vat://error-codes / vat://supported-countries / vat://spec	免费
提示词	vat_compliance_guide / explain_vat_result	免费

涵盖欧盟 27 国 + GB + XI（北爱尔兰）。每个国家/地区还包含其母语名称，以及更实用的VAT 号码当地叫法，这是人们实际会搜索的内容：

代码 Code	母语名 Native	当地 VAT 叫法 Local VAT term	中文	English	EU
AT	Österreich	UID-Nummer	奥地利	Austria	✅
BE	België / Belgique	BTW-nummer / numéro de TVA	比利时	Belgium	✅
BG	България	ДДС номер	保加利亚	Bulgaria	✅
CY	Κύπρος / Kıbrıs	Αριθμός ΦΠΑ	塞浦路斯	Cyprus	✅
CZ	Česko	DIČ	捷克	Czech Republic	✅
DE	Deutschland	USt-IdNr.	德国	Germany	✅
DK	Danmark	CVR-nummer	丹麦	Denmark	✅
EE	Eesti	KMKR number	爱沙尼亚	Estonia	✅
EL	Ελλάδα	Αριθμός ΦΠΑ	希腊	Greece	✅
ES	España	NIF (IVA)	西班牙	Spain	✅
FI	Suomi	ALV-numero	芬兰	Finland	✅
FR	France	numéro de TVA	法国	France	✅
HR	Hrvatska	PDV broj	克罗地亚	Croatia	✅
HU	Magyarország	ÁFA-szám	匈牙利	Hungary	✅
IE	Ireland / Éire	VAT number	爱尔兰	Ireland	✅
IT	Italia	Partita IVA	意大利	Italy	✅
LT	Lietuva	PVM kodas	立陶宛	Lithuania	✅
LU	Lëtzebuerg / Luxembourg	numéro TVA	卢森堡	Luxembourg	✅
LV	Latvija	PVN numurs	拉脱维亚	Latvia	✅
MT	Malta	VAT number	马耳他	Malta	✅
NL	Nederland	btw-nummer	荷兰	Netherlands	✅
PL	Polska	NIP	波兰	Poland	✅
PT	Portugal	NIF	葡萄牙	Portugal	✅
RO	România	cod de TVA	罗马尼亚	Romania	✅
SE	Sverige	momsregistreringsnummer	瑞典	Sweden	✅
SI	Slovenija	ID za DDV	斯洛文尼亚	Slovenia	✅
SK	Slovensko	IČ DPH	斯洛伐克	Slovakia	✅
GB	United Kingdom	VAT registration number	英国	United Kingdom	—
XI	Northern Ireland	VAT registration number (XI)	北爱尔兰	Northern Ireland	—

叫法遵循当地常见商务用法 — 部分国家/地区接受多种形式；表中列出最主要的一种。 叫法遵循当地常见商务用法 — 部分国家/地区接受多种形式；表中列出最主要的一种。

快速开始（本地）

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

使用 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 <APIFY_TOKEN>。

调用示例

格式预检查（免费）

{ "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": "..." }

错误代码（摘录）

Code	中文	EN
VAT_FORMAT_INVALID	格式不符	format mismatch
VAT_VIES_INVALID	VIES 判定无效	VIES says invalid
VIES_MS_UNAVAILABLE	成员国系统不可用	member state down
VIES_TIMEOUT	超时	timeout
NETWORK_ERROR	网络错误	network error

完整表格可通过 get_error_codes 或 vat://error-codes 获取。

部署（Apify 按事件付费）

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

定价配置位于 .actor/actor.json → pricingEvents：格式、错误和国家/地区查询均免费；仅 mcp-validate-vat 计费。

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 接口频繁限流、偶发停机，缓存 + 优雅降级是必选项。
• 零冷启动成本 —— 免费官方数据源，叠加一层封装 + 可解释的双语输出，按事件计费。

你能拿到什么

能力	说明	计费
validate_vat	先做免费本地格式校验，再按需调用欧盟官方 VIES 接口核验真实性；结构化 + 双语错误	$0.0005 / 次（2026-11-06 起 $0.005）
check_vat_format	纯本地正则格式校验，零网络、零成本	免费
list_supported_countries	返回支持国家（母语名 + 当地 VAT 叫法 + 中/英）	免费
get_error_codes	返回完整中英双语错误码表	免费
resources	vat://error-codes / vat://supported-countries / vat://spec	免费
prompts	vat_compliance_guide / explain_vat_result	免费

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

代码 Code	母语名 Native	当地 VAT 叫法 Local VAT term	中文	English	EU
AT	Österreich	UID-Nummer	奥地利	Austria	✅
BE	België / Belgique	BTW-nummer / numéro de TVA	比利时	Belgium	✅
BG	България	ДДС номер	保加利亚	Bulgaria	✅
CY	Κύπρος / Kıbrıs	Αριθμός ΦΠΑ	塞浦路斯	Cyprus	✅
CZ	Česko	DIČ	捷克	Czech Republic	✅
DE	Deutschland	USt-IdNr.	德国	Germany	✅
DK	Danmark	CVR-nummer	丹麦	Denmark	✅
EE	Eesti	KMKR number	爱沙尼亚	Estonia	✅
EL	Ελλάδα	Αριθμός ΦΠΑ	希腊	Greece	✅
ES	España	NIF (IVA)	西班牙	Spain	✅
FI	Suomi	ALV-numero	芬兰	Finland	✅
FR	France	numéro de TVA	法国	France	✅
HR	Hrvatska	PDV broj	克罗地亚	Croatia	✅
HU	Magyarország	ÁFA-szám	匈牙利	Hungary	✅
IE	Ireland / Éire	VAT number	爱尔兰	Ireland	✅
IT	Italia	Partita IVA	意大利	Italy	✅
LT	Lietuva	PVM kodas	立陶宛	Lithuania	✅
LU	Lëtzebuerg / Luxembourg	numéro TVA	卢森堡	Luxembourg	✅
LV	Latvija	PVN numurs	拉脱维亚	Latvia	✅
MT	Malta	VAT number	马耳他	Malta	✅
NL	Nederland	btw-nummer	荷兰	Netherlands	✅
PL	Polska	NIP	波兰	Poland	✅
PT	Portugal	NIF	葡萄牙	Portugal	✅
RO	România	cod de TVA	罗马尼亚	Romania	✅
SE	Sverige	momsregistreringsnummer	瑞典	Sweden	✅
SI	Slovenija	ID za DDV	斯洛文尼亚	Slovenia	✅
SK	Slovensko	IČ DPH	斯洛伐克	Slovakia	✅
GB	United Kingdom	VAT registration number	英国	United Kingdom	—
XI	Northern Ireland	VAT registration number (XI)	北爱尔兰	Northern Ireland	—

叫法取当地商务常用写法；部分国家有不止一种官方接受的写法，表中列最主要的那种。 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 <APIFY_TOKEN>。

调用示例

格式预校验（免费）

{ "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": "..." }

错误码（节选）

代码	中文	EN
VAT_FORMAT_INVALID	格式不符	format mismatch
VAT_VIES_INVALID	VIES 判定无效	VIES says invalid
VIES_MS_UNAVAILABLE	成员国系统不可用	member state down
VIES_TIMEOUT	超时	timeout
NETWORK_ERROR	网络错误	network error

完整表见 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 介面頻繁限流、偶發停機，快取 + 優雅降級是必選項。
• 零冷啟動成本 —— 免費官方資料源，疊加一層封裝 + 可解釋的雙語輸出，按事件計費。

你能拿到什麼

能力	說明	計費
validate_vat	先做免費本地格式校驗，再依需求呼叫歐盟官方 VIES 介面核驗真實性；結構化 + 雙語錯誤	$0.0005 / 次（2026-11-06 起 $0.005）
check_vat_format	純本地正則格式校驗，零網路、零成本	免費
list_supported_countries	回傳支援國家（母語名 + 當地 VAT 叫法 + 中/英）	免費
get_error_codes	回傳完整中英雙語錯誤碼表	免費
resources	vat://error-codes / vat://supported-countries / vat://spec	免費
prompts	vat_compliance_guide / explain_vat_result	免費

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

代码 Code	母语名 Native	当地 VAT 叫法 Local VAT term	中文	English	EU
AT	Österreich	UID-Nummer	奥地利	Austria	✅
BE	België / Belgique	BTW-nummer / numéro de TVA	比利时	Belgium	✅
BG	България	ДДС номер	保加利亚	Bulgaria	✅
CY	Κύπρος / Kıbrıs	Αριθμός ΦΠΑ	塞浦路斯	Cyprus	✅
CZ	Česko	DIČ	捷克	Czech Republic	✅
DE	Deutschland	USt-IdNr.	德国	Germany	✅
DK	Danmark	CVR-nummer	丹麦	Denmark	✅
EE	Eesti	KMKR number	爱沙尼亚	Estonia	✅
EL	Ελλάδα	Αριθμός ΦΠΑ	希腊	Greece	✅
ES	España	NIF (IVA)	西班牙	Spain	✅
FI	Suomi	ALV-numero	芬兰	Finland	✅
FR	France	numéro de TVA	法国	France	✅
HR	Hrvatska	PDV broj	克罗地亚	Croatia	✅
HU	Magyarország	ÁFA-szám	匈牙利	Hungary	✅
IE	Ireland / Éire	VAT number	爱尔兰	Ireland	✅
IT	Italia	Partita IVA	意大利	Italy	✅
LT	Lietuva	PVM kodas	立陶宛	Lithuania	✅
LU	Lëtzebuerg / Luxembourg	numéro TVA	卢森堡	Luxembourg	✅
LV	Latvija	PVN numurs	拉脱维亚	Latvia	✅
MT	Malta	VAT number	马耳他	Malta	✅
NL	Nederland	btw-nummer	荷兰	Netherlands	✅
PL	Polska	NIP	波兰	Poland	✅
PT	Portugal	NIF	葡萄牙	Portugal	✅
RO	România	cod de TVA	罗马尼亚	Romania	✅
SE	Sverige	momsregistreringsnummer	瑞典	Sweden	✅
SI	Slovenija	ID za DDV	斯洛文尼亚	Slovenia	✅
SK	Slovensko	IČ DPH	斯洛伐克	Slovakia	✅
GB	United Kingdom	VAT registration number	英国	United Kingdom	—
XI	Northern Ireland	VAT registration number (XI)	北爱尔兰	Northern Ireland	—

叫法取当地商务常用写法；部分国家有不止一种官方接受的写法，表中列最主要的那种。 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 <APIFY_TOKEN>。

呼叫範例

格式預校驗（免費）

{ "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": "..." }

錯誤碼（節選）

代碼	中文	EN
VAT_FORMAT_INVALID	格式不符	format mismatch
VAT_VIES_INVALID	VIES 判定無效	VIES says invalid
VIES_MS_UNAVAILABLE	成員國系統不可用	member state down
VIES_TIMEOUT	逾時	timeout
NETWORK_ERROR	網路錯誤	network error

完整表見 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。

---

License

MIT — see LICENSE.

Privacy

Read-only and stateless — no accounts, no personal data collected. Submitted VAT numbers are forwarded to the official EU VIES service and may be held in a memory-only cache. See PRIVACY.md.

---

Support · 赞助 · 贊助

EN — VIES VAT Validator MCP is open source (MIT), ad-free. It is funded by the community, not by ads. If it powers your agents or workflow, please support it:

• ☕ Ko-fi (the Sponsor ❤️ button on this repo routes here): https://ko-fi.com/panstories

简体中文 — VIES VAT Validator MCP 开源（MIT）、无广告，由社区资助而非广告。若它支撑了你的智能体或工作流，欢迎赞助：点本仓库的 Sponsor 按钮（跳转 Ko-fi）或前往 https://ko-fi.com/panstories

繁體中文 — VIES VAT Validator MCP 開源（MIT）、無廣告，由社群資助而非廣告。若它支撐了你的智能體或工作流，歡迎贊助：點本倉庫的 Sponsor 按鈕（導向 Ko-fi）或前往 https://ko-fi.com/panstories

Thank you! · 谢谢 · 謝謝 💙