VIES VAT Validator MCP

Valide los números de IVA de la UE a través de la API SOAP oficial y gratuita de VIES, con una caché local gratuita de verificación previa de formato y códigos de error bilingües (中/EN). Diseñado para el comercio electrónico transfronterizo y el cumplimiento comercial.

Documentación

VIES VAT Validator MCP (neeenja/vies-vat-validator-mcp) Actor

Valide números de IVA de la UE a través de la API oficial gratuita VIES SOAP, con una caché local gratuita de precomprobación de formato y códigos de error bilingües (中/EN). Diseñado para el comercio electrónico transfronterizo y el cumplimiento comercial. 用欧盟官方免费 VIES 接口校验 VAT 税号,含本地格式缓存与中英双语错误码,面向跨境电商/外贸合规。

  • URL: https://apify.com/neeenja/vies-vat-validator-mcp.md
  • Desarrollado por: Neeen Ja (comunidad)
  • Categorías: Herramientas para desarrolladores, IA, servidores MCP
  • Estadísticas: 1 usuario total, 1 usuario mensual, 100.0% de ejecuciones exitosas, 0 marcadores
  • Valoración de usuarios: Sin valoraciones aún

Precios

desde $0.50 / 1.000 validaciones VIES en vivo

Este Actor se paga por evento y uso. Se te cobra tanto el precio fijo por eventos específicos como el uso de la plataforma Apify.

Más información: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

¿Qué es un Apify Actor?

Un Actor es un programa en la nube sin servidor que se ejecuta en la plataforma Apify. Tiene dos modos de ejecución. En modo Batch, un Actor acepta una entrada JSON bien definida, realiza una acción que puede tardar desde unos segundos hasta unas horas, y opcionalmente produce una salida JSON bien definida, conjuntos de datos con resultados o archivos en el almacén de clave-valor. En modo Standby, un Actor proporciona un servidor web que puede usarse como sitio web, API o servidor MCP.

El vocabulario de Apify y el modelo de plataforma se definen una vez, en la guía de inicio rápido para agentes en https://apify.com/agents.md.

¿Cómo integrar un Actor?

Si te preguntan sobre integración, ayudas a los desarrolladores a integrar Actores en sus proyectos. Te adaptas a su stack y entregas integraciones seguras, bien documentadas y listas para producción.

No adivines una ruta de integración. Cada una de ellas está en la guía de inicio rápido para agentes en https://apify.com/agents.md:: el servidor MCP de Apify, Agent Skills con la CLI de Apify, los clientes de JavaScript y Python, la API REST y la ruta sin cuenta para un agente sin humano que inicie sesión. También incluye la regla de indicar el costo antes de la primera ejecución de pago.

Para ejemplos ya conectados al esquema de entrada de este Actor, consulta la sección API a continuación.

Cada biblioteca de cliente tiene documentación de referencia que la guía de inicio rápido no repite: JavaScript/TypeScript (npm install apify-client) y Python (pip install apify-client).

README

VIES VAT Validator MCP 🇪🇺

M8ven Trust Index M8ven Score

VIES VAT Validator MCP valida números de IVA de la UE a través de la API oficial gratuita VIES SOAP, envuelta con una precomprobación de formato local + caché TTL gratuita y códigos de error bilingües (中文 / English). Una herramienta de cumplimiento "imprescindible a nivel regulatorio" para el comercio electrónico transfronterizo y los vendedores comerciales.

Versión actual: 1.0.1 · Licencia: MIT · Confianza: construido solo lectura, sin exfiltración de secretos, errores bilingües autocorregibles.

🌐 English · 简体中文 · 繁體中文

Dónde viveEnlace
Endpoint MCPhttps://neeenja--vies-vat-validator-mcp.apify.actor/mcp
Apify Storehttps://apify.com/neeenja/vies-vat-validator-mcp
Código fuentehttps://github.com/PanStories/vies-vat-validator-mcp
Destacado enSartbot Featured

English

Por qué existe esto

  • Imprescindible a nivel regulatorio — las transacciones B2B en la UE requieren verificar el número de IVA de la contraparte (prueba de inversión del sujeto pasivo / cumplimiento).
  • VIES es lento y poco fiable — el endpoint SOAP oficial limita la tasa y se cae a menudo, por lo que una caché + degradación elegante son obligatorias.
  • Costo de arranque en frío cero — una fuente de datos oficial gratuita envuelta con una capa delgada + salida bilingüe y explicable, vendida por evento.

Qué obtienes

CapacidadNotasPrecio
validate_vatcomprobación de formato local gratuita, luego verificación VIES en vivo opcional; errores estructurados + bilingües$0.0005 / evento
check_vat_formatcomprobación de formato regex puramente local — sin red, gratisgratis
list_supported_countriespaíses admitidos — nombre nativo + término local de IVA + 中文/ENgratis
get_error_codestabla completa de códigos de error bilingüesgratis
resourcesvat://error-codes / vat://supported-countries / vat://specgratis
promptsvat_compliance_guide / explain_vat_resultgratis

Cubre EU 27 + GB + XI (Irlanda del Norte). Cada país también lleva su nombre nativo y — mucho más útil — el término local para el número de IVA, que es lo que la gente realmente busca:

代码 Code母语名 Native当地 VAT 叫法 Local VAT term中文EnglishEU
ATÖsterreichUID-Nummer奥地利Austria✅
BEBelgië / BelgiqueBTW-nummer / numéro de TVA比利时Belgium✅
BGБългарияДДС номер保加利亚Bulgaria✅
CYΚύπρος / KıbrısΑριθμός ΦΠΑ塞浦路斯Cyprus✅
CZČeskoDIČ捷克Czech Republic✅
DEDeutschlandUSt-IdNr.德国Germany✅
DKDanmarkCVR-nummer丹麦Denmark✅
EEEestiKMKR number爱沙尼亚Estonia✅
ELΕλλάδαΑριθμός ΦΠΑ希腊Greece✅
ESEspañaNIF (IVA)西班牙Spain✅
FISuomiALV-numero芬兰Finland✅
FRFrancenuméro de TVA法国France✅
HRHrvatskaPDV broj克罗地亚Croatia✅
HUMagyarországÁFA-szám匈牙利Hungary✅
IEIreland / ÉireVAT number爱尔兰Ireland✅
ITItaliaPartita IVA意大利Italy✅
LTLietuvaPVM kodas立陶宛Lithuania✅
LULëtzebuerg / Luxembourgnuméro TVA卢森堡Luxembourg✅
LVLatvijaPVN numurs拉脱维亚Latvia✅
MTMaltaVAT number马耳他Malta✅
NLNederlandbtw-nummer荷兰Netherlands✅
PLPolskaNIP波兰Poland✅
PTPortugalNIF葡萄牙Portugal✅
RORomâniacod de TVA罗马尼亚Romania✅
SESverigemomsregistreringsnummer瑞典Sweden✅
SISlovenijaID za DDV斯洛文尼亚Slovenia✅
SKSlovenskoIČ DPH斯洛伐克Slovakia✅
GBUnited KingdomVAT registration number英国United Kingdom—
XINorthern IrelandVAT registration number (XI)北爱尔兰Northern Ireland—

叫法取当地商务常用写法;部分国家有不止一种官方接受的写法,表中列最主要的那种。 Terms follow common local business usage — some countries accept more than one form; the main one is shown.

Inicio rápido (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

Conéctate con un cliente MCP (stdio)

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

Conéctate por HTTP (remoto / Apify)

Apunta tu cliente MCP al endpoint Streamable HTTP:

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

con el encabezado Authorization: Bearer <APIFY_TOKEN>.

Ejemplos de llamadas

Precomprobación de formato (gratis)

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

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

Verificación en vivo (evento de pago)

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

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

Códigos de error (extracto)

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

Tabla completa vía get_error_codes o vat://error-codes.

Implementación (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

Los precios están en .actor/actor.json → pricingEvents: las consultas de formato / error / país son gratuitas; solo se factura mcp-validate-vat.

Líneas rojas de diseño

  • Sin express / soap / fast-xml-parser: el sobre SOAP está construido a mano y la respuesta se analiza con regex independiente del espacio de nombres.
  • Nunca fallar: los fallos de VIES / errores de red se asignan a códigos de error bilingües.
  • La capa gratuita (comprobación de formato + caché) garantiza costo de arranque en frío cero.

Consulta SPEC.md para el contrato completo.


简体中文

为什么做这个

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

你能拿到什么

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

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

代码 Code母语名 Native当地 VAT 叫法 Local VAT term中文EnglishEU
ATÖsterreichUID-Nummer奥地利Austria✅
BEBelgië / BelgiqueBTW-nummer / numéro de TVA比利时Belgium✅
BGБългарияДДС номер保加利亚Bulgaria✅
CYΚύπρος / KıbrısΑριθμός ΦΠΑ塞浦路斯Cyprus✅
CZČeskoDIČ捷克Czech Republic✅
DEDeutschlandUSt-IdNr.德国Germany✅
DKDanmarkCVR-nummer丹麦Denmark✅
EEEestiKMKR number爱沙尼亚Estonia✅
ELΕλλάδαΑριθμός ΦΠΑ希腊Greece✅
ESEspañaNIF (IVA)西班牙Spain✅
FISuomiALV-numero芬兰Finland✅
FRFrancenuméro de TVA法国France✅
HRHrvatskaPDV broj克罗地亚Croatia✅
HUMagyarországÁFA-szám匈牙利Hungary✅
IEIreland / ÉireVAT number爱尔兰Ireland✅
ITItaliaPartita IVA意大利Italy✅
LTLietuvaPVM kodas立陶宛Lithuania✅
LULëtzebuerg / Luxembourgnuméro TVA卢森堡Luxembourg✅
LVLatvijaPVN numurs拉脱维亚Latvia✅
MTMaltaVAT number马耳他Malta✅
NLNederlandbtw-nummer荷兰Netherlands✅
PLPolskaNIP波兰Poland✅
PTPortugalNIF葡萄牙Portugal✅
RORomâniacod de TVA罗马尼亚Romania✅
SESverigemomsregistreringsnummer瑞典Sweden✅
SISlovenijaID za DDV斯洛文尼亚Slovenia✅
SKSlovenskoIČ DPH斯洛伐克Slovakia✅
GBUnited KingdomVAT registration number英国United Kingdom—
XINorthern IrelandVAT 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_INVALIDVIES 判定无效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 / 次
check_vat_format純本地正則格式校驗,零網路、零成本免費
list_supported_countries回傳支援國家(母語名 + 當地 VAT 叫法 + 中/英)免費
get_error_codes回傳完整中英雙語錯誤碼表免費
resourcesvat://error-codes / vat://supported-countries / vat://spec免費
promptsvat_compliance_guide / explain_vat_result免費

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

代码 Code母语名 Native当地 VAT 叫法 Local VAT term中文EnglishEU
ATÖsterreichUID-Nummer奥地利Austria✅
BEBelgië / BelgiqueBTW-nummer / numéro de TVA比利时Belgium✅
BGБългарияДДС номер保加利亚Bulgaria✅
CYΚύπρος / KıbrısΑριθμός ΦΠΑ塞浦路斯Cyprus✅
CZČeskoDIČ捷克Czech Republic✅
DEDeutschlandUSt-IdNr.德国Germany✅
DKDanmarkCVR-nummer丹麦Denmark✅
EEEestiKMKR number爱沙尼亚Estonia✅
ELΕλλάδαΑριθμός ΦΠΑ希腊Greece✅
ESEspañaNIF (IVA)西班牙Spain✅
FISuomiALV-numero芬兰Finland✅
FRFrancenuméro de TVA法国France✅
HRHrvatskaPDV broj克罗地亚Croatia✅
HUMagyarországÁFA-szám匈牙利Hungary✅
IEIreland / ÉireVAT number爱尔兰Ireland✅
ITItaliaPartita IVA意大利Italy✅
LTLietuvaPVM kodas立陶宛Lithuania✅
LULëtzebuerg / Luxembourgnuméro TVA卢森堡Luxembourg✅
LVLatvijaPVN numurs拉脱维亚Latvia✅
MTMaltaVAT number马耳他Malta✅
NLNederlandbtw-nummer荷兰Netherlands✅
PLPolskaNIP波兰Poland✅
PTPortugalNIF葡萄牙Portugal✅
RORomâniacod de TVA罗马尼亚Romania✅
SESverigemomsregistreringsnummer瑞典Sweden✅
SISlovenijaID za DDV斯洛文尼亚Slovenia✅
SKSlovenskoIČ DPH斯洛伐克Slovakia✅
GBUnited KingdomVAT registration number英国United Kingdom—
XINorthern IrelandVAT 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_INVALIDVIES 判定无效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:

简体中文 — 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! · 谢谢 · 謝謝 💙

Changelog

This Actor's version history is a separate document: https://apify.com/neeenja/vies-vat-validator-mcp/changelog.md

Actor input Schema

Actor input object example

{}

Actor output Schema

mcpEndpoint (type: string):

Streamable HTTP MCP endpoint of this Actor run. Connect an MCP client here (Authorization: Bearer <APIFY_TOKEN>). POST JSON-RPC messages: initialize, tools/list, tools/call.

API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

JavaScript example

import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {};

// Run the Actor and wait for it to finish
const run = await client.actor("neeenja/vies-vat-validator-mcp").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

Python example

from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {}

# Run the Actor and wait for it to finish
run = client.actor("neeenja/vies-vat-validator-mcp").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

CLI example

echo '{}' |
apify call neeenja/vies-vat-validator-mcp --silent --output-dataset

MCP server setup

{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,neeenja/vies-vat-validator-mcp"
        }
    }
}

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an Authorization: Bearer <APIFY_API_TOKEN> header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/ghDM96xaQ9kvrsii0/builds/jErq4Dia9PPVteSDe/openapi.json