Schwaizer Zefix Mcp

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. zefixsearchcompanies - Search for Swiss companies using the Zefix API.
2. zefixgetcompanybyuid - Get detailed company information from Zefix by UID, with optional UID Webservice enrichment.
3. zefixgetdaily_registrations - Get all company registrations and publications from SOGC for a specific date.
4. zefixgetcompany_publications - Get all SOGC publications for a specific company by UID.

UID Webservice Tools

1. uidadvancedsearch - Advanced company search using the UID Webservice.
2. uidvalidateuid - Validate a Swiss UID.
3. uidvalidatevat_number - Validate a Swiss VAT number.
4. uidgetcompany_details - Get detailed company information using only the UID Webservice.

Combined API Tools

1. generateduediligence_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:

• Zefix API: Contact Zefix support zefix@bj.admin.ch
• UID Webservice: Contact uid@bfs.admin.ch
• This MCP Server: Open an issue on GitHub

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ishumilin
• Source: ishumilin/schwaizer-zefix-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.