vatnode

vatnode-mcp

Servidor oficial de Model Context Protocol para vatnode — validación de IVA y datos fiscales de la UE para agentes de IA.

Permite que los asistentes de IA (Claude Desktop, Cursor, ChatGPT, Continue, Cline, …) consulten tipos de IVA, verifiquen formatos de números de IVA y validen identificadores de IVA contra el servicio VIES de la UE sin salir del chat.

• Gratuito, sin conexión — tipos de IVA y comprobaciones de formato para 45 países europeos, sin necesidad de cuenta
• Validación en vivo — verifica números de IVA de la UE contra VIES, obtén la empresa registrada + número de consulta con grado de auditoría (requiere una clave API gratuita de vatnode; el número de consulta se genera una vez que configuras tu propio IVA como solicitante en los ajustes del panel)
• Cinco herramientas enfocadas — bien descritas para una selección precisa de herramientas por parte del agente
• Stdio puro, cero dependencias alojadas, se ejecuta localmente mediante npx

---

Herramientas

Herramienta	Gratuita	Descripción
get_country_vat_rates	✅	Tipos estándar / reducido / superreducido / estacionamiento + formato de número de IVA para un país
list_eu_vat_rates	✅	Los 27 estados miembros de la UE (más XI para Irlanda del Norte) de una sola vez
check_vat_format	✅	Comprobación sintáctica sin conexión de un número de IVA contra la expresión regular del país
list_supported_countries	✅	Los 45 países admitidos y cuáles admiten validación VIES completa
validate_vat_number	🔑	Validación VIES en vivo — devuelve validez, nombre de la empresa, dirección, fecha de registro y (cuando se configura un IVA de solicitante en los ajustes del panel) un número de consulta con grado de auditoría

Las herramientas gratuitas funcionan completamente sin conexión: los datos se incluyen mediante eu-vat-rates-data y se actualizan diariamente desde el TEDB de la Comisión Europea.

validate_vat_number requiere una clave API de vatnode. El nivel gratuito incluye una cuota mensual de solicitudes — consíguela en 30 segundos.

---

Instalación

Claude Desktop

Añade a tu claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vatnode": {
      "command": "npx",
      "args": ["-y", "vatnode-mcp"],
      "env": {
        "VATNODE_API_KEY": "vat_live_..."
      }
    }
  }
}

Reinicia Claude Desktop. Las herramientas de vatnode aparecerán en el selector de herramientas.

Puedes omitir VATNODE_API_KEY si solo necesitas las herramientas gratuitas (tipos, comprobaciones de formato).

Cursor

Configuración → MCP → Añadir nuevo servidor:

{
  "mcpServers": {
    "vatnode": {
      "command": "npx",
      "args": ["-y", "vatnode-mcp"],
      "env": { "VATNODE_API_KEY": "vat_live_..." }
    }
  }
}

ChatGPT (conectores personalizados / SDK de Apps)

Configúralo como un servidor MCP stdio con el mismo comando npx -y vatnode-mcp. Consulta la documentación del SDK de Apps.

Continue / Cline / otros clientes

Cualquier cliente compatible con MCP puede conectarse: apúntalo a npx -y vatnode-mcp y (opcionalmente) pasa VATNODE_API_KEY mediante el entorno.

---

Obtén una clave API

validate_vat_number requiere una cuenta de vatnode. La plataforma también ofrece cosas que el MCP no expone:

• Webhooks para cambios de estado del IVA (supervisa el IVA de un cliente de forma continua)
• Validación por lotes
• Respaldo de base de datos nacional cuando VIES está caído
• Números de consulta VIES (prueba de validación con grado de auditoría)
• Límite de velocidad por clave + análisis del panel

Regístrate gratis →

---

Sesión de ejemplo

Tú: ¿Cuál es el tipo de IVA en Finlandia y Alemania?

(El agente llama a get_country_vat_rates para FI y DE — gratuito, sin clave.)

Agente: El IVA estándar de Finlandia es del 25,5%, el de Alemania es del 19%. Finlandia tiene tipos reducidos del 14% y 10%; Alemania tiene el 7%.

Tú: ¿Es IE6388047V un IVA válido?

(El agente llama a validate_vat_number — requiere clave API.)

Agente: Sí, es válido. Registrado a GOOGLE IRELAND LIMITED en Gordon House, Barrow Street, Dublín 4.

---

Configuración

Variable de entorno	Obligatoria	Predeterminado	Propósito
VATNODE_API_KEY	para validate_vat_number	—	Clave API de https://vatnode.dev
VATNODE_API_URL	no	https://api.vatnode.dev	Anula la base de la API (autoalojamiento / staging)

---

Contribuciones

Se aceptan informes de errores y PRs. Abre primero un issue para cambios no triviales para que podamos alinearnos en la dirección.

git clone https://github.com/vatnode/vatnode-mcp.git
cd vatnode-mcp
npm install
npm test

Publicación

Las versiones se publican en npm mediante Trusted Publishing — sin secreto NPM_TOKEN, cada versión firmada con procedencia npm.

# bump the version in ALL of: package.json, src/index.ts (VERSION),
# and server.json (top-level "version" + packages[0].version — the MCP
# Registry publish reads server.json and rejects a duplicate version).
# Commit, then:
git tag v0.3.2
git push --tags

CI en .github/workflows/release.yml recoge la etiqueta y publica.

Licencia

MIT