swiss-ip-mcp

🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide/swiss-public-data-mcp)**

# 💡 swiss-ip-mcp

**MCP Server for Swiss Intellectual Property Data (IGE/IPI)**

![Version](https://img.shields.io/badge/version-1.1.6-blue)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)
[![Data Source](https://img.shields.io/badge/Data-swissreg.ch-red)](https://www.swissreg.ch/public/apidocs/)
[![CI](https://github.com/malkreide/swiss-ip-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/malkreide/swiss-ip-mcp/actions)

🇩🇪 [Deutsche Version → README.de.md](README.de.md)

---

## Overview

`swiss-ip-mcp` is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that gives AI models structured, language-driven access to the Swiss intellectual property register [Swissreg](https://www.swissreg.ch), operated by the **Swiss Federal Institute of Intellectual Property (IGE/IPI)**.

It is the successor to [`patent-mcp`](https://github.com/malkreide/patent-mcp) and covers all available domains of the [Swissreg Datadelivery API](https://www.swissreg.ch/public/apidocs/): trademarks, patents, patent publications, and supplementary protection certificates (SPC/ESZ).

**This server is model-agnostic.** It works with Claude, GPT-4, Llama, and any other MCP-compatible client – not just Claude Desktop.

![Demo: Claude querying the Swiss trademark register via swiss-ip-mcp](docs/assets/demo.svg)

---

## Example Queries

The real power is natural language. Instead of manually searching the register, just ask a question:

> "Which trademarks does the City of Zurich hold at the IGE?"

> "Is the name 'Learning City Zurich' registered as a trademark in Switzerland?"

> "Which pharmaceutical companies have filed Swiss patents in the last six months?"

> "Show me all trademark applications in the education sector (Nice class 41) since January 2025."

> "What supplementary protection certificates does Novartis hold in Switzerland?"

---

## Covered Domains

| Domain | Description |
|--------|-------------|
| **Trademarks** | Swiss trademark register – filing, protection, owners, Nice classes |
| **Patents** | CH patents – filing, grant, IPC classes, applicants, inventors |
| **Patent publications** | Official patent publications in the Swiss Official Gazette |
| **SPC / ESZ** | Supplementary protection certificates for medicinal and plant-protection products |

> **Note:** Design search is not yet available in the Swissreg Datadelivery API.

---

## Tools (11)

| Tool | Function |
|------|---------|
| `swiss_ip_search_trademarks` | Free-text trademark search (wildcard `*` supported) |
| `swiss_ip_get_trademark` | Retrieve a trademark by registration number |
| `swiss_ip_search_trademarks_by_owner` | Find all trademarks held by a given owner |
| `swiss_ip_search_trademarks_by_class` | Filter trademarks by Nice classification class |
| `swiss_ip_search_patents` | Free-text patent search |
| `swiss_ip_get_patent` | Retrieve a patent by number |
| `swiss_ip_search_patents_by_applicant` | Find patents by applicant or inventor name |
| `swiss_ip_search_patent_publications` | Search patent publications |
| `swiss_ip_search_spc` | SPC/ESZ search (pharma and plant protection) |
| `swiss_ip_search_recent_filings` | Filter filings by date range across all domains |
| `swiss_ip_get_quota` | Check remaining API data transfer quota |

### Resources & Prompts

Beyond tools, the server exposes two more MCP primitives:

**Resources** (read-only metadata, `swissip://` URI scheme):

| URI | Content |
|-----|---------|
| `swissip://about` | Server + data-source metadata (provenance, covered domains) |
| `swissip://domains` | List of covered IP domains |

**Prompts** (curated workflow templates):

| Prompt | Arguments | Purpose |
|--------|-----------|---------|
| `trademark_availability` | `name` | Check whether a name is a registered Swiss trademark |
| `competitor_ip_report` | `company` | IP overview (trademarks + patents) for a company |
| `recent_ip_filings_report` | `ip_type, date_from, date_to` | Report on recent filings in a period |

### Error semantics

Tool **execution errors** (API failures, timeouts, missing credentials) are
returned with MCP `isError: true` and a masked, user-friendly message — internal
details (stack traces, raw API bodies) go only to the server log. A specific
number lookup that finds nothing is **not** an error: it returns a normal result
with `match_type: "none"` and a `message`.

---

## Project Phase

This server is in **Phase 1 (read-only)** of the MCP phased-rollout model: every
tool is read-only and writes nothing. See [`ROADMAP.md`](ROADMAP.md) for the
phase plan and the prerequisites for any future write-capable phase.

---

## Architecture

```
AI client (Claude Desktop, Cursor, VS Code + Continue, …)
         │
         │  MCP (stdio or SSE)
         ▼
   swiss-ip-mcp
         │
         │  HTTPS + OAuth2 (IGE IDP)
         ▼
  Swissreg Datadelivery API
  https://www.swissreg.ch/public/api/v1
         │
         ├── TrademarkSearch
         ├── PatentSearch
         ├── PatentPublicationSearch
         ├── SPCSearch
         └── UserQuota
```

### Transport Modes

| Transport | Use case | Configuration |
|-----------|----------|---------------|
| **stdio** | Claude Desktop, local development | Default (no extra setup) |
| **Streamable HTTP** | Cloud deployment (Render.com etc.) | `MCP_TRANSPORT=streamable-http` |
| **SSE** | Legacy HTTP clients | `MCP_TRANSPORT=sse` |

Transport is selected at startup from the `MCP_TRANSPORT` environment variable
(default `stdio`). The HTTP transports are served by uvicorn and honour:

| Variable | Default | Purpose |
|----------|---------|---------|
| `MCP_HOST` | `127.0.0.1` | Bind address. Use `0.0.0.0` **only** inside a container / behind a reverse proxy. |
| `PORT` / `MCP_PORT` | `8000` | Bind port (`PORT` wins — PaaS convention). |
| `MCP_ALLOWED_ORIGINS` | _(empty)_ | Comma-separated CORS origin allow-list. No wildcard in production. |
| `MCP_ALLOWED_HOSTS` | _(empty)_ | Comma-separated `Host`-header allow-list; enables DNS-rebinding protection when set. |

The `Mcp-Session-Id` header is exposed via CORS so browser-based clients can
read and echo it on follow-up requests.

---

## Prerequisites

1. **IGE credentials** (free): Sign the [terms of use](https://www.ige.ch/en/services/digital-resources/ip-data/data-delivery-api) and send the form by post to the IGE. Credentials are issued upon receipt.
2. **Python 3.11 or later**
3. **`uv`** (recommended) or `pip`

---

## Installation

```bash
# Run directly with uv (recommended, no local installation needed)
uvx swiss-ip-mcp

# Local development installation
git clone https://github.com/malkreide/swiss-ip-mcp
cd swiss-ip-mcp
pip install -e ".[dev]"
```

---

## Configuration

### Environment Variables

```bash
export IGE_USERNAME="your_username"
export IGE_PASSWORD="your_password"
```

### Claude Desktop

Open the config file:
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "swiss-ip": {
      "command": "uvx",
      "args": ["swiss-ip-mcp"],
      "env": {
        "IGE_USERNAME": "your_username",
        "IGE_PASSWORD": "your_password"
      }
    }
  }
}
```

### Other MCP Clients

`swiss-ip-mcp` is compatible with any MCP-capable client:

| Client | Configuration |
|--------|--------------|
| Cursor | Add to `~/.cursor/mcp.json` (same format as Claude Desktop) |
| VS Code + Continue | Add via `continue.json` MCP server block |
| Windsurf | Add via MCP server settings |
| Self-hosted (mcp-proxy) | Use SSE transport with `MCP_TRANSPORT=sse` |

### Cloud / Render.com (Streamable HTTP)

```bash
MCP_TRANSPORT=streamable-http \
  MCP_HOST=0.0.0.0 PORT=8000 \
  MCP_ALLOWED_ORIGINS="https://your-client.example" \
  MCP_ALLOWED_HOSTS="your-app.onrender.com" \
  IGE_USERNAME=... IGE_PASSWORD=... \
  swiss-ip-mcp
```

> **Security note:** bind to `0.0.0.0` only inside a container or behind a
> reverse proxy. Always set `MCP_ALLOWED_ORIGINS` and `MCP_ALLOWED_HOSTS` for
> public deployments — this enables CORS scoping and DNS-rebinding protection.
> The endpoint is unauthenticated and serves only public IP-register data; do
> not place credentialed or non-public tools behind this transport without
> adding authentication first.

### Docker / Kubernetes

A hardened multi-stage [`Dockerfile`](Dockerfile) (non-root UID 10001,
`HEALTHCHECK` on `/health`), a [`docker-compose.yml`](docker-compose.yml) with
resource limits, and Kubernetes manifests + an HAProxy sticky-session config
under [`deploy/`](deploy/) are included.

```bash
docker compose up --build   # reads IGE_* from .env
```

See [`docs/deployment.md`](docs/deployment.md) for hardening, resource limits and
scaling (stateless vs. sticky-session) details.

---

## Tests

```bash
# Unit tests (no credentials needed)
PYTHONPATH=src pytest tests/ -v

# Including live integration tests against the real API
IGE_USERNAME=... IGE_PASSWORD=... PYTHONPATH=src pytest tests/ -v
```

The CI workflow runs on Python 3.11, 3.12, and 3.13.

---

## Observability (optional)

The server can emit OpenTelemetry traces — one span per tool call plus child
spans for the backend Swissreg/IDP HTTP calls. Tracing is **off by default** and
adds no overhead until enabled.

```bash
pip install 'swiss-ip-mcp[otel]'

MCP_OTEL_ENABLED=1 \
  OTEL_EXPORTER_OTLP_ENDPOINT=http://your-collector:4318 \
  MCP_ENV=production \
  swiss-ip-mcp
```

| Variable | Purpose |
|----------|---------|
| `MCP_OTEL_ENABLED` | Set to `1` to enable trace export (or just set the endpoint below). |
| `OTEL_EXPORTER_OTLP_ENDPOINT` |