使用说明
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) │<────│ │<────│ (REST, JSON) │
└─────────────┘ │ Format │ └─────────────────┘
│ Validation │ ┌─────────────────┐
│ + Routing │────>│ EU VIES API │
│ │<────│ (REST, JSON) │
└──────────────┘ └─────────────────┘
- 格式验证 --根据国家特定的正则表达式模式检查增值税ID
- 智能路由 --德国合格确认书送达BZSt；VIES进行简单验证
- 结构化结果 --返回带有德语描述、匹配代码和可操作指南的JSON
工具
validate_ustidnr --检查单个增值税ID
| 参数 | 类型 | 说明 |
|---|---|---|
vat_id |
str |
用于验证的欧盟增值税ID（例如。， DE123456789) |
{
"vat_id": "FR12345678901",
"valid": true,
"error_code": "200",
"error_description": "Die angefragte USt-IdNr. ist gültig.",
"country_code": "FR",
"company_name": "Acme SARL",
"company_address": "1 Rue de Rivoli, 75001 Paris"
}
validate_batch --一次最多检查100个增值税ID
| 参数 | 类型 | 说明 |
|---|---|---|
vat_ids |
list[str] |
要验证的欧盟增值税ID列表 |
{
"total": 3,
"valid_count": 2,
"invalid_count": 1,
"error_count": 0,
"results": [...]
}
qualified_confirmation --核实公司身份（UStG第6a条）
对从事欧盟跨境贸易的德国企业进行法律要求的检查。
| 参数 | 类型 | 说明 |
|---|---|---|
own_vat_id |
str |
您的德国USt IdNr（必须以DE开头） |
partner_vat_id |
str |
合作伙伴欧盟税号 |
company_name |
str |
预期公司名称 |
city |
str |
预期城市 |
zip_code |
str |
预期邮政编码 |
street |
str |
预期街道 |
{
"own_vat_id": "DE123456789",
"partner_vat_id": "FR12345678901",
"valid": true,
"error_code": "200",
"company_name_match": "A",
"city_match": "A",
"zip_match": "A",
"street_match": "B",
"all_fields_match": false
}
匹配代码：
| 代码 | 含义 | 该怎么办 |
|---|---|---|
| A. | 匹配 | 一切正常——成员国确认的数据 |
| B | 不匹配 | 停止-发货前与您的贸易伙伴核实 |
| C | 未请求 | 字段未发送以供检查 |
| D | 不可用 | 成员国不提供此数据 |
为什么选择此服务器？
现有5个以上的增值税验证MCP服务器——都是简单的VIES包装器。这个更进一步：
| 功能 | 仅支持VIES的mcp | ustidnr mcp |
|---|---|---|
| 简单验证 | 是 | 是 |
| 合格确认 | 否 | 是 （BZSt eVatR） |
| §6a UStG合规性 | 否 | 是 |
| 批量验证 | 否 | 是 （最多100个） |
| 德语校验位 | 否 | 是 （型号11,10） |
| 德语提示 | 否 | 是 （8个提示） |
| 参考资源 | 否 | 是 （4个资源） |
| BZSt新REST API（2025） | 不适用 | 是 |
法律背景
为什么这很重要？
德国企业在申请跨境交付的零税率增值税之前，必须核实欧盟贸易伙伴的增值税ID。如果没有适当的验证，在欺诈案件中，您有可能对买方未支付的增值税承担责任（美国税法第25d条）。
这 合格确认 （合格确认） creates 信任保护 （信托保护）根据§6a Abs。4 UStG——这是你的法律盾牌。
简单确认与合格确认
| 简单 | 合格 | |
|---|---|---|
| 检查有效性 | 是 | 是 |
| 检查公司名称 | 否 | 是 |
| 检查地址 | 否 | 是（城市、邮政编码、街道） |
| 法律保护 | 基本 | 全面（《美国法典》第6a条第4款） |
| 用于 | 常规检查 | 所有欧盟跨境交付 |
与einvoice mcp配合使用效果极佳
与一起使用 einvoice mcp 有关完整的德国-欧盟发票工作流程：
- 验证 买方的增值税ID
- 合格确认 验证公司身份
- 生成 合规的XRechnung/ZUGFeRD发票
- 嵌入 发票票据中的确认结果
“检查 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 查看完整列表。
| 变量 | 默认值 | 描述 |
|---|---|---|
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
文档
许可证
麻省理工学院
