schwaizer-zefix-mcp

ishumilin/schwaizer-zefix-mcp

3.2

If you are the rightful owner of schwaizer-zefix-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

Schwaizer's MCP Server provides unofficial access to Swiss Company Registry data through Zefix REST API and UID Webservice.

Tools
9
Resources
0
Prompts
0

Schwaizer

MCP Server: Zefix & UID Webservice

An unofficial MCP server for interacting with the Swiss Commercial Register.

This is a community project by Schwaizer and is not an official implementation by the Swiss government.

About Schwaizer

SHAPING SWITZERLAND'S AI FUTURE Empowering Swiss businesses and society through responsible AI adoption. Founded in 2025, Schwaizer is a non-profit organization dedicated to accelerating the responsible adoption of artificial intelligence across Switzerland.

Website: https://www.schwaizer.ch

Zefix MCP Server

MCP (Model Context Protocol) server providing access to Swiss Company Registry data through Zefix REST API and UID Webservice.

Features

Dual API Integration

  • Zefix REST API: Fast company searches and SOGC (Official Gazette) tracking
  • UID Webservice: Rich company data including NOGA codes, VAT details, and commercial register information

Available Tools (9 tools)

Zefix API Tools
  1. zefix_search_companies - Search for Swiss companies using the Zefix API.
  2. zefix_get_company_by_uid - Get detailed company information from Zefix by UID, with optional UID Webservice enrichment.
  3. zefix_get_daily_registrations - Get all company registrations and publications from SOGC for a specific date.
  4. zefix_get_company_publications - Get all SOGC publications for a specific company by UID.
UID Webservice Tools
  1. uid_advanced_search - Advanced company search using the UID Webservice.
  2. uid_validate_uid - Validate a Swiss UID.
  3. uid_validate_vat_number - Validate a Swiss VAT number.
  4. uid_get_company_details - Get detailed company information using only the UID Webservice.
Combined API Tools
  1. generate_due_diligence_report - Generate a comprehensive due diligence report combining data from both Zefix and UID Webservice.

Installation

npm install

Configuration

Copy .env.example to .env and configure:

# Zefix REST API Credentials (required for Zefix tools)
# Note: Credentials must be requested from Federal Registry of Commerce
ZEFIX_USERNAME=your_username
ZEFIX_PASSWORD=your_password

# UID Webservice (no auth needed for Public Services)
UID_PUBLIC_URL=https://www.uid-wse.admin.ch/V5.0/PublicServices.svc?wsdl

# Optional settings
CACHE_ENABLED=true
CACHE_TTL=3600
LOG_LEVEL=info

Usage

Running the Server

npm start

Example Tool Calls

Search for companies (Zefix)
{
  "name": "zefix_search_companies",
  "arguments": {
    "name": "Migros",
    "canton": "ZH",
    "activeOnly": true
  }
}
Get company details (Zefix + UID)
{
  "name": "zefix_get_company_by_uid",
  "arguments": {
    "uid": "CHE-123.456.789",
    "enrichWithUidData": true
  }
}
Validate UID (UID Webservice)
{
  "name": "uid_validate_uid",
  "arguments": {
    "uid": "CHE-123.456.789"
  }
}
Generate due diligence report (Zefix + UID)
{
  "name": "generate_due_diligence_report",
  "arguments": {
    "uid": "CHE-123.456.789",
    "includePublications": true
  }
}
Get daily registrations (Zefix)
{
  "name": "zefix_get_daily_registrations",
  "arguments": {
    "date": "2025-11-15"
  }
}

API Documentation

Zefix REST API

  • Base URL: https://www.zefix.admin.ch/ZefixPublicREST/api/v1
  • Authentication: Basic Auth
  • SOGC publications:
    • Per-company publications are returned via GET /api/v1/company/uid/{uid} in the sogcPub[] field of the company payload (there is no GET /api/v1/sogc/uid/{uid} endpoint).
    • Daily publications are available via GET /api/v1/sogc/bydate/{date}.

UID Webservice

  • Public Services URL: https://www.uid-wse.admin.ch/V5.0/PublicServices.svc?wsdl
  • Protocol: SOAP
  • Authentication: None required for Public Services

Data Sources

  • Zefix: Federal Commercial Register (Handelsregister)
  • UID Register: Federal Business and Enterprise Register
  • SOGC/SHAB: Swiss Official Gazette of Commerce

Caching

The server implements intelligent caching:

  • Search results: 30 minutes
  • Company details: 1 hour
  • SOGC data: 6 hours
  • UID/VAT validation: 1-24 hours
  • Reference data: 24 hours

Error Handling

All tools include comprehensive error handling:

  • Input validation with Zod schemas
  • API error handling with retries
  • Graceful fallbacks when enrichment fails
  • Detailed error messages in responses

Development

Project Structure

zefix-mcp-server/
├── src/
│   ├── index.js              # MCP server entry point
│   ├── config.js             # Configuration
│   ├── api/
│   │   ├── zefix-client.js   # Zefix REST client
│   │   ├── uid-client.js     # UID SOAP client
│   │   └── schemas.js        # Validation schemas
│   ├── tools/
│   │   ├── company-search.js # Search tools
│   │   ├── validation.js     # Validation tools
│   │   ├── sogc.js          # SOGC tools
│   │   └── due-diligence.js # Due diligence tool
│   └── utils/
│       ├── logger.js         # Logging
│       ├── cache.js          # Caching
│       └── formatting.js     # Formatting utilities
├── .env                      # Environment variables
├── package.json
└── README.md

Running Tests

npm test

Linting

npm run lint

Scripts

Helper scripts (for local development and manual checks):

  • scripts/describe-wsdl.mjs — Inspect/describe UID Webservice WSDL structure
  • scripts/test-uid-search.mjs — Exercise UID search endpoints with sample queries
  • scripts/test-uid-search-variants.mjs — Try multiple UID search variants

Run examples:

node scripts/describe-wsdl.mjs
node scripts/test-uid-search.mjs "CHE-123.456.789"
node scripts/test-uid-search-variants.mjs "Migros"

License

MIT

Support

For issues with: