ustidnr-mcp

Validate EU VAT IDs directly from your AI assistant. Ask Claude to check a VAT number, verify a trading partner's details, or batch-validate your entire customer list — powered by the official German BZSt API.

The only MCP server that supports qualifizierte Bestätigung (qualified confirmation) — the legally required proof for German businesses conducting EU cross-border transactions under §6a UStG.

No API key required. The BZSt eVatR API is a free public service.

What Can It Do?

Just ask your AI assistant in plain language:

Works in German and English — all 8 built-in prompts are in German, but the tools understand both languages.

Quick Start

Install via Smithery (recommended)

npx -y @smithery/cli install ustidnr-mcp --client claude

Install via pip

pip install ustidnr-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "ustidnr": {
      "command": "ustidnr-mcp"
    }
  }
}

Claude Code

claude mcp add ustidnr-mcp -- ustidnr-mcp

Docker

docker compose -f docker/docker-compose.yml up -d --build

Features at a Glance

How It Works

┌─────────────┐     ┌──────────────┐     ┌─────────────────┐
│  MCP Client │────>│ ustidnr-mcp  │────>│  BZSt eVatR API │
│  (Claude)   │<────│              │<────│  (REST, JSON)   │
└─────────────┘     │  Format      │     └─────────────────┘
                    │  Validation  │     ┌─────────────────┐
                    │  + Routing   │────>│  EU VIES API    │
                    │              │<────│  (REST, JSON)   │
                    └──────────────┘     └─────────────────┘

1. Format validation — Checks VAT ID against country-specific regex pattern
2. Smart routing — German qualified confirmation goes to BZSt; simple validation goes to VIES
3. Structured results — Returns JSON with German descriptions, match codes, and actionable guidance

Tools

validate_ustidnr — Check a single VAT ID

{
  "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 — Check up to 100 VAT IDs at once

{
  "total": 3,
  "valid_count": 2,
  "invalid_count": 1,
  "error_count": 0,
  "results": [...]
}

qualified_confirmation — Verify company identity (§6a UStG)

The legally required check for German businesses doing EU cross-border trade.

{
  "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
}

Match codes:

Why This Server?

There are 5+ existing VAT validation MCP servers — all are simple VIES wrappers. This one goes further:

Legal Background

Why does this matter?

German businesses must verify EU trading partners' VAT IDs before claiming zero-rate VAT on cross-border deliveries. Without proper verification, you risk being liable for your buyer's unpaid VAT in fraud cases (§25d UStG).

The qualified confirmation (qualifizierte Bestätigung) creates Vertrauensschutz (trust protection) under §6a Abs. 4 UStG — it's your legal shield.

Simple vs. Qualified Confirmation

Works Great With einvoice-mcp

Use together with einvoice-mcp for a complete German EU invoicing workflow:

1. Validate the buyer's VAT ID
2. Qualified confirmation to verify company identity
3. Generate a compliant XRechnung/ZUGFeRD invoice
4. Embed the confirmation result in invoice notes

"Prüfe die USt-IdNr von FR12345678901 und erstelle dann eine XRechnung"

Error Codes

Troubleshooting

Configuration

All settings via environment variables. See .env.example for the full list.

Limitations

• Qualified confirmation requires a German USt-IdNr as own_vat_id — this is a BZSt requirement
• Single validation uses VIES — BZSt requires both own + partner IDs, so single-ID checks go through VIES
• Current status only — the new BZSt REST API does not support historical/date-range queries
• Rate limits — BZSt enforces session-based rate limits for qualified confirmations
• Member state availability — some EU countries temporarily refuse validation requests (error codes 203/217)

Compliance Proof

401 tests | 98% coverage | 45 security tests | 27 EU countries | all BZSt error codes

Development

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

Documentation

• Compliance Guide — §6a UStG requirements, decision tree, error codes
• Deployment Guide — Docker, Smithery, Render.com, Claude Desktop

License

MIT