内容
# 欧盟增值税验证解决方案
[](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)
完整的欧盟增值税验证解决方案 - 支持n8n集成和Claude Desktop的REST API服务器。
## 🚀 快速部署选项
### 部署到Coolify
[](COOLIFY_DEPLOYMENT.md)
### 使用Docker部署
```bash
docker run -p 3000:3000 ghcr.io/jazib/check-vat-vies-mcp:latest
```
### 部署到Railway
[](https://railway.app/template/deploy?template=https://github.com/jazib/check-vat-vies-mcp&envs=PORT&optionalEnvs=PORT&PORTDesc=API+服务器端口&PORTDefault=3000)
### 部署到Render
[](https://render.com/deploy?repo=https://github.com/jazib/check-vat-vies-mcp)
## ✨ 功能特点
- 🔍 **实时增值税验证** - 使用官方VIES服务验证欧盟增值税号码
- 🤖 **REST API** - 简单的HTTP端点，易于集成
- 🔗 **n8n Ready** - 预建的工作流和示例
- 🖥️ **MCP服务器** - Claude Desktop集成，支持AI驱动的验证
- 🐳 **Docker支持** - 生产环境下的容器化支持
- 🌍 **所有欧盟国家** - 支持所有27个欧盟成员国
- ⚡ **自动检测** - 自动从增值税号码中提取国家代码
- 📊 **健康监测** - 内置健康检查和状态端点
## 📦 安装
### 选项1：运行API服务器
```bash
# 克隆仓库
git clone https://github.com/jazib/check-vat-vies-mcp.git
cd check-vat-vies-mcp
# 安装依赖
npm install
# 编译TypeScript
npm run build
# 启动API服务器
node api-server.js
```
### 选项2：Docker
```bash
# 使用Docker Compose
docker-compose up
# 或手动构建和运行
docker build -f Dockerfile.api -t vat-api .
docker run -p 3000:3000 vat-api
```
### 选项3：使用预构建的Docker镜像
```bash
docker run -p 3000:3000 ghcr.io/jazib/check-vat-vies-mcp:latest
```
## 🔌 API端点
| 端点 | 方法 | 描述 |
|----------|--------|-------------|
| `/health` | GET | 健康检查 |
| `/api/member-states` | GET | 列出所有欧盟国家 |
| `/api/validate` | POST | 使用国家代码和号码验证 |
| `/api/validate/auto` | POST | 自动检测和验证 |
| `/api/status` | GET | 检查VIES服务状态 |
### 示例请求
```bash
curl -X POST http://localhost:3000/api/validate/auto \
-H "Content-Type: application/json" \
-d '{"vat":"DE215891388"}'
```
### 示例响应
```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集成
预建的n8n工作流，适用于：
- 单个增值税验证
- 从Google Sheets进行批处理
- 与webhook的CRM集成
- 调度VIES状态监控
参见 [N8N_WORKFLOWS.md](N8N_WORKFLOWS.md) 获取完整示例。
## 🤖 MCP服务器（Claude Desktop）
添加到您的Claude Desktop配置：
```json
{
"mcpServers": {
"vies-vat-checker": {
"command": "node",
"args": ["/path/to/check-vat-vies-mcp/dist/index.js"],
"env": {},
"description": "欧盟增值税验证"
}
}
}
```
## 🌍 支持的国家
所有27个欧盟成员国：
`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`
## 🔒 环境变量
```env
PORT=3000 # API服务器端口
NODE_ENV=production # Node环境
RATE_LIMIT=60 # 每分钟请求数（可选）
ALLOWED_ORIGINS=* # CORS配置（可选）
API_KEY=secret # API身份验证（可选）
```
## 📚 文档
- [API文档](API_DOCUMENTATION.md) - 完整的API参考
- [Coolify部署](COOLIFY_DEPLOYMENT.md) - 部署到Coolify指南
- [n8n工作流](N8N_WORKFLOWS.md) - 集成示例
- [贡献](CONTRIBUTING.md) - 如何贡献
## 🧪 开发
```bash
# 在开发模式下运行
npm run dev
# 运行测试
npm test
# 代码检查
npm run lint
# 编译TypeScript
npm run build
```
## 🐳 Docker Hub
Docker镜像会自动构建并发布到GitHub容器注册表中：
```bash
docker pull ghcr.io/jazib/check-vat-vies-mcp:latest
```
## 📄 许可证
MIT - 参见 [LICENSE](LICENSE) 文件
## 🤝 贡献
欢迎贡献！请先阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 🐛 问题
发现了bug？ [在此报告](https://github.com/jazib/check-vat-vies-mcp/issues)
## ⭐ 支持
如果您觉得这个项目有帮助，请给它一个星标！
---
以 ❤️ 制作，为欧盟商业社区服务
