# Schwaizer Zefix Mcp

> MCP server for interacting with the Swiss Commercial Register (Zefix) and UID Webservice APIs

- **Type:** MCP server
- **Install:** `agentstack add mcp-ishumilin-schwaizer-zefix-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [ishumilin](https://agentstack.voostack.com/s/ishumilin)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [ishumilin](https://github.com/ishumilin)
- **Source:** https://github.com/ishumilin/schwaizer-zefix-mcp

## Install

```sh
agentstack add mcp-ishumilin-schwaizer-zefix-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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
5. **uid_advanced_search** - Advanced company search using the UID Webservice.
6. **uid_validate_uid** - Validate a Swiss UID.
7. **uid_validate_vat_number** - Validate a Swiss VAT number.
8. **uid_get_company_details** - Get detailed company information using only the UID Webservice.

#### Combined API Tools
9. **generate_due_diligence_report** - Generate a comprehensive due diligence report combining data from both Zefix and UID Webservice.

## Installation

```bash
npm install
```

## Configuration

Copy `.env.example` to `.env` and configure:

```env
# 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

```bash
npm start
```

### Example Tool Calls

#### Search for companies (Zefix)
```javascript
{
  "name": "zefix_search_companies",
  "arguments": {
    "name": "Migros",
    "canton": "ZH",
    "activeOnly": true
  }
}
```

#### Get company details (Zefix + UID)
```javascript
{
  "name": "zefix_get_company_by_uid",
  "arguments": {
    "uid": "CHE-123.456.789",
    "enrichWithUidData": true
  }
}
```

#### Validate UID (UID Webservice)
```javascript
{
  "name": "uid_validate_uid",
  "arguments": {
    "uid": "CHE-123.456.789"
  }
}
```

#### Generate due diligence report (Zefix + UID)
```javascript
{
  "name": "generate_due_diligence_report",
  "arguments": {
    "uid": "CHE-123.456.789",
    "includePublications": true
  }
}
```

#### Get daily registrations (Zefix)
```javascript
{
  "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
```bash
npm test
```

### Linting
```bash
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:
```bash
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](https://github.com/ishumilin)
- **Source:** [ishumilin/schwaizer-zefix-mcp](https://github.com/ishumilin/schwaizer-zefix-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-ishumilin-schwaizer-zefix-mcp
- Seller: https://agentstack.voostack.com/s/ishumilin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.