vatnode

vatnode-mcp

Servidor oficial do Model Context Protocol para vatnode — validação de IVA e dados fiscais da UE para agentes de IA.

Permite que assistentes de IA (Claude Desktop, Cursor, ChatGPT, Continue, Cline, …) consultem taxas de IVA, verifiquem formatos de números de IVA e validem IDs de IVA contra o serviço VIES da UE sem sair do chat.

• Gratuito, offline — taxas de IVA e verificações de formato para 45 países europeus, sem necessidade de conta
• Validação ao vivo — verifique números de IVA da UE contra o VIES, obtenha a empresa registrada + número de consulta com nível de auditoria (requer uma chave de API vatnode gratuita; o número de consulta é gerado quando você define seu próprio IVA como solicitante nas Configurações do painel)
• Cinco ferramentas focadas — bem descritas para seleção precisa de ferramentas pelo agente
• Stdio puro, zero dependências hospedadas, executa localmente via npx

---

Ferramentas

Ferramenta	Gratuita	Descrição
get_country_vat_rates	✅	Taxas padrão / reduzida / super-reduzida / estacionamento + formato do número de IVA para um país
list_eu_vat_rates	✅	Todos os 27 estados-membros da UE (mais XI para Irlanda do Norte) de uma vez
check_vat_format	✅	Verificação sintática offline de um número de IVA contra o regex do país
list_supported_countries	✅	Todos os 45 países suportados e quais oferecem validação VIES completa
validate_vat_number	🔑	Validação VIES ao vivo — retorna validade, nome da empresa, endereço, data de registro e (quando um IVA de solicitante é definido nas Configurações do painel) um número de consulta com nível de auditoria

As ferramentas gratuitas funcionam totalmente offline — os dados são incluídos via eu-vat-rates-data e atualizados diariamente a partir do TEDB da Comissão Europeia.

validate_vat_number requer uma chave de API vatnode. O plano gratuito inclui uma cota mensal de solicitações — obtenha uma em 30 segundos.

---

Instalação

Claude Desktop

Adicione ao seu 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_..."
      }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas vatnode aparecerão no seletor de ferramentas.

Você pode omitir VATNODE_API_KEY se precisar apenas das ferramentas gratuitas (taxas, verificações de formato).

Cursor

Configurações → MCP → Adicionar novo servidor:

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

ChatGPT (conectores personalizados / Apps SDK)

Configure como um servidor MCP stdio com o mesmo comando npx -y vatnode-mcp. Consulte a documentação do Apps SDK.

Continue / Cline / outros clientes

Qualquer cliente compatível com MCP pode se conectar — aponte para npx -y vatnode-mcp e (opcionalmente) passe VATNODE_API_KEY via ambiente.

---

Obtenha uma chave de API

validate_vat_number requer uma conta vatnode. A plataforma também oferece recursos que o MCP não expõe:

• Webhooks para mudanças de status de IVA (monitore o IVA de um cliente continuamente)
• Validação em lote
• Fallback para banco de dados nacional quando o VIES está fora do ar
• Números de consulta VIES (prova de validação com nível de auditoria)
• Limitação de taxa por chave + análises no painel

Cadastre-se gratuitamente →

---

Exemplo de sessão

Você: Qual é a taxa de IVA na Finlândia e na Alemanha?

(O agente chama get_country_vat_rates para FI e DE — gratuito, sem chave.)

Agente: O IVA padrão da Finlândia é 25,5%, o da Alemanha é 19%. A Finlândia tem taxas reduzidas de 14% e 10%; a Alemanha tem 7%.

Você: IE6388047V é um IVA válido?

(O agente chama validate_vat_number — requer chave de API.)

Agente: Sim, é válido. Registrado para GOOGLE IRELAND LIMITED em Gordon House, Barrow Street, Dublin 4.

---

Configuração

Variável de ambiente	Obrigatória	Padrão	Finalidade
VATNODE_API_KEY	para validate_vat_number	—	Chave de API de https://vatnode.dev
VATNODE_API_URL	não	https://api.vatnode.dev	Substituir a base da API (self-hosting / staging)

---

Contribuindo

Relatórios de bugs e PRs são bem-vindos. Abra uma issue primeiro para mudanças não triviais para que possamos alinhar a direção.

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

Lançamentos

Os lançamentos são publicados no npm via Trusted Publishing — sem segredo NPM_TOKEN, cada lançamento assinado com proveniência 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 no .github/workflows/release.yml captura a tag e publica.

Licença

MIT