ustidnr-mcp
     
直接从您的AI助手验证欧盟增值税ID。 请Claude检查增值税号码，核实贸易伙伴的详细信息，或批量验证您的整个客户名单-由德国官方BZSt API提供支持。
唯一支持的MCP服务器 合格确认 （合格确认）——德国企业根据《美国贸易法公约》第6a条进行欧盟跨境交易所需的法律证明。
不需要API密钥。 BZSt eVatR API是一项免费的公共服务。
______________________________________________________________________
它能做什么？
用简单的语言问你的人工智能助手：
| 你说。.. | 发生了什么 |
|---|---|
| *“DE123456789是有效的增值税ID吗？”* | 格式检查+API实时验证 |
| *“检查FR12345678901是否属于巴黎的Acme SARL”* | 姓名和地址匹配的合格确认 |
| *“验证我的客户列表中的所有增值税ID”* | 并行批量验证多达100个ID |
| *“我可以用IT12345678901进行反向充电吗？”* | 检查§13b UStG的先决条件 |
| *“检查 VAT ID，然后创建发票”* | 与合作 einvoice mcp 完整的工作流程 |
作品 德语和英语 --所有8个内置提示都是德语的，但这些工具可以理解这两种语言。
______________________________________________________________________
快速开始
通过Smithery安装（推荐）
npx -y @smithery/cli install ustidnr-mcp --client claude通过pip安装
pip install ustidnr-mcp克劳德桌面版
添加 claude_desktop_config.json:
{
"mcpServers": {
"ustidnr": {
"command": "ustidnr-mcp"
}
}
}克劳德代码
claude mcp add ustidnr-mcp -- ustidnr-mcp码头工人
docker compose -f docker/docker-compose.yml up -d --build______________________________________________________________________
功能概览
| 特性 | 描述 |
|---|---|
| 简单验证 | 格式检查+VIES/BZSt API查找任何欧盟增值税ID |
| 批量验证 | 并行验证多达100个增值税ID |
| 合格确认 | 将公司名称和地址与官方BZSt记录相匹配（UStG第6a条） |
| 27个欧盟国家 | 具有国家特定模式的完整格式验证 |
| 德语校验码 | 用于DE VAT ID的ISO/IEC 7064 MOD 11,10算法 |
| 8德国提示 | 用于常见税务合规任务的预构建工作流程 |
| 4参考资源 | EU格式、BZSt错误代码、§6a UStG指南、校验位算法 |
| 不需要API密钥 | BZSteVatR是一个免费的公共政府API |
______________________________________________________________________
运作原理
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ MCP Client │────>│ ustidnr-mcp │────>│ BZSt eVatR API │
│ (Claude) ││ EU VIES API │
│ │ *“检查 FR12345678901 的增值税号，然后创建 X 发票”*
______________________________________________________________________
## 错误代码
|代码|描述|
|------|-------------|
| `200` |有效|
| `201` |格式无效|
| `202` |未注册（未分配）|
| `203` |会员国服务不可用|
| `204` |自己的增值税ID无效|
| `205` |自己的增值税ID不是德语|
| `206` |不是欧盟成员国|
| `207` |价格有限|
| `208` |内部BZSt错误|
| `217` |服务暂时不可用|
| `219` |确认合格后有效|
______________________________________________________________________
## 故障排除
|问题|解决方案|
|---------|----------|
| `error_code: 203` |成员国暂时不可用--稍后重试|
| `error_code: 207` |速率受限--在发送更多请求之前等待|
| `error_code: 204` |您自己的德国USt IdNr无效，请仔细检查|
| `error_code: 205` |自己的增值税ID必须是德语（DE前缀）才能进行合格确认|
|所有匹配代码 `D` |该成员国不提供地址数据|
|超时错误|增加 `REQUEST_TIMEOUT` env变量（默认值：30s）|
______________________________________________________________________
## 配置
所有设置均通过环境变量进行。看 [`.env.example`](.env.example) 查看完整列表。
|变量|默认值|描述|
|----------|---------|-------------|
| `LOG_LEVEL` | `INFO` |日志冗长|
| `MCP_TRANSPORT` | `stdio` | `stdio` 或 `streamable-http` |
| `BZST_BASE_URL` | `https://api.evatr.vies.bzst.de/app/v1/abfrage` |BZSt REST API端点|
| `REQUEST_TIMEOUT` | `30.0` |HTTP超时（秒）|
| `BATCH_MAX_SIZE` | `100` |最大批量|
______________________________________________________________________
## 局限性
- **合格的确认需要德国USt IdNr** 作为 `own_vat_id` --这是BZSt的要求
- **单一验证使用VIES** --BZSt需要自己的+合作伙伴ID，因此单个ID检查需要通过VIES进行
- **仅当前状态** -新的BZSt REST API不支持历史/日期范围查询
- **费率限制** --BZSt对合格的确认执行基于会话的速率限制
- **成员国可用性** --一些欧盟国家暂时拒绝验证请求（错误代码203/217）
______________________________________________________________________
## 合规证明
> **401项测试|覆盖率98%| 45项安全测试| 27个欧盟国家|所有BZSt错误代码**
|类别|测试|覆盖范围|
|----------|-------|----------|
|格式验证（27个欧盟国家）|80+|98%|
|BZSt REST API客户端|60+|96%|
|VIES回退客户端|30+|100%|
|安全性（OWASP前10名）|45+|100%|
|提示和资源|40+|100%|
|型号和配置|50+|100%|
|集成流程|20+|--|
|自定义例外|10+|100%|
|模块| Stmts | Miss |封面|
|--------|-------|------|-------|
| `bzst_client.py` | 79 | 3 | 96% |
| `vies_client.py` | 43 | 0 | 100% |
| `validator.py` | 46 | 1 | 98% |
| `models.py` | 71 | 0 | 100% |
| `errors.py` | 19 | 0 | 100% |
| `config.py` | 15 | 0 | 100% |
| `prompts.py` | 29 | 1 | 97% |
| `resources.py` | 21 | 0 | 100% |
| **总计** | **328** | **7** | **98%** |
______________________________________________________________________
## 发展
make install # Install with dev dependencies make test # Run tests (95%+ coverage required) make lint # Lint with ruff make type-check # Type check with mypy --strict make fmt # Auto-format make build # Build wheel make docker-up # Run in Docker
## 文档
- [合规指南](docs/COMPLIANCE_GUIDE.md) --§6a UStG要求、决策树、错误代码
- [部署指南](docs/DEPLOYMENT.md) --Docker、Smithery、Render.com、Claude Desktop
______________________________________________________________________
## 许可证
麻省理工学院