🇪🇺 VAT Validation API & MCP Server

Docker Image Tests License: MIT

Complete VAT validation solution for EU businesses - REST API server with n8n integration and MCP support for Claude Desktop.

🚀 Quick Deploy Options

Deploy to Coolify

Deploy with Docker

docker run -p 3000:3000 ghcr.io/jazib/check-vat-vies-mcp:latest

Deploy to Railway

Deploy on Railway

Deploy to Render

✨ Features

🔍 Real-time VAT Validation - Validate EU VAT numbers using official VIES service
🤖 REST API - Simple HTTP endpoints for easy integration
🔗 n8n Ready - Pre-built workflows and examples
🖥️ MCP Server - Claude Desktop integration for AI-powered validation
🐳 Docker Support - Production-ready containerization
🌍 All EU Countries - Support for all 27 EU member states
⚡ Auto-detection - Automatically extract country code from VAT numbers
📊 Health Monitoring - Built-in health check and status endpoints

📦 Installation

Option 1: Run the API Server

# Clone the repository git clone https://github.com/jazib/check-vat-vies-mcp.git cd check-vat-vies-mcp # Install dependencies npm install # Build TypeScript npm run build # Start the API server node api-server.js

Option 2: Docker

# Using Docker Compose docker-compose up # Or build and run manually docker build -f Dockerfile.api -t vat-api . docker run -p 3000:3000 vat-api

Option 3: Use Pre-built Docker Image

docker run -p 3000:3000 ghcr.io/jazib/check-vat-vies-mcp:latest

🔌 API Endpoints

Endpoint	Method	Description
`/health`	GET	Health check
`/api/member-states`	GET	List all EU countries
`/api/validate`	POST	Validate with country code + number
`/api/validate/auto`	POST	Auto-detect and validate
`/api/status`	GET	Check VIES service status

Example Request

curl -X POST http://localhost:3000/api/validate/auto \ -H "Content-Type: application/json" \ -d '{"vat":"DE215891388"}'

Example Response

{ "success": true, "input": "DE215891388", "processed": { "countryCode": "DE", "vatNumber": "215891388" }, "data": { "countryCode": "DE", "vatNumber": "215891388", "isValid": true, "requestDate": "2025-09-26T18:00:00.000Z", "companyName": "Example GmbH", "companyAddress": "Berlin, Germany" } }

🔧 n8n Integration

Ready-to-use n8n workflows for:

Single VAT validation
Batch processing from Google Sheets
CRM integration with webhooks
Scheduled VIES status monitoring

See N8N_WORKFLOWS.md for complete examples.

🤖 MCP Server (Claude Desktop)

Add to your Claude Desktop config:

{ "mcpServers": { "vies-vat-checker": { "command": "node", "args": ["/path/to/check-vat-vies-mcp/dist/index.js"], "env": {}, "description": "EU VAT validation" } } }

🌍 Supported Countries

All 27 EU member states: AT BE BG CY CZ DE DK EE EL ES FI FR HR HU IE IT LT LU LV MT NL PL PT RO SE SI SK

🔒 Environment Variables

PORT=3000 # API server port NODE_ENV=production # Node environment RATE_LIMIT=60 # Requests per minute (optional) ALLOWED_ORIGINS=* # CORS configuration (optional) API_KEY=secret # API authentication (optional)

📚 Documentation

API Documentation - Complete API reference
Coolify Deployment - Deploy to Coolify guide
n8n Workflows - Integration examples
Contributing - How to contribute

🧪 Development

# Run in development mode npm run dev # Run tests npm test # Lint code npm run lint # Build TypeScript npm run build

🐳 Docker Hub

The Docker image is automatically built and published to GitHub Container Registry:

docker pull ghcr.io/jazib/check-vat-vies-mcp:latest

📄 License

MIT - see LICENSE file

🤝 Contributing

Contributions are welcome! Please read CONTRIBUTING.md first.

🐛 Issues

Found a bug? Report it here

⭐ Support

If you find this project useful, please give it a star!

Made with ❤️ for the EU business community

Deploy Server

HTTP connection URL

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

Enables real-time validation of EU VAT numbers using the official VIES service. Supports all 27 EU member states with automatic country code detection and provides company information for valid VAT numbers.

VAT Validation MCP Server