Content
# 🇪🇺 VAT Validation API & MCP Server
[](https://github.com/jazib/check-vat-vies-mcp/actions/workflows/docker-publish.yml)
[](https://github.com/jazib/check-vat-vies-mcp/actions/workflows/test.yml)
[](https://opensource.org/licenses/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
[](COOLIFY_DEPLOYMENT.md)
### Deploy with Docker
```bash
docker run -p 3000:3000 ghcr.io/jazib/check-vat-vies-mcp:latest
```
### Deploy to Railway
[](https://railway.app/template/deploy?template=https://github.com/jazib/check-vat-vies-mcp&envs=PORT&optionalEnvs=PORT&PORTDesc=Port+for+the+API+server&PORTDefault=3000)
### Deploy to Render
[](https://render.com/deploy?repo=https://github.com/jazib/check-vat-vies-mcp)
## ✨ 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
```bash
# 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
```bash
# 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
```bash
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
```bash
curl -X POST http://localhost:3000/api/validate/auto \
-H "Content-Type: application/json" \
-d '{"vat":"DE215891388"}'
```
### Example Response
```json
{
"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](N8N_WORKFLOWS.md) for complete examples.
## 🤖 MCP Server (Claude Desktop)
Add to your Claude Desktop config:
```json
{
"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
```env
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](API_DOCUMENTATION.md) - Complete API reference
- [Coolify Deployment](COOLIFY_DEPLOYMENT.md) - Deploy to Coolify guide
- [n8n Workflows](N8N_WORKFLOWS.md) - Integration examples
- [Contributing](CONTRIBUTING.md) - How to contribute
## 🧪 Development
```bash
# 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:
```bash
docker pull ghcr.io/jazib/check-vat-vies-mcp:latest
```
## 📄 License
MIT - see [LICENSE](LICENSE) file
## 🤝 Contributing
Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) first.
## 🐛 Issues
Found a bug? [Report it here](https://github.com/jazib/check-vat-vies-mcp/issues)
## ⭐ Support
If you find this project useful, please give it a star!
---
Made with ❤️ for the EU business community
