🇪🇺 VAT Validation API & MCP Server

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 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