swiss-ip-mcp

🇨🇭 属于 瑞士公共数据 MCP 组合

💡 swiss-ip-mcp

瑞士知识产权数据 MCP 服务（IGE/IPI）

🇩🇪 德语版 → README.de.md

---

概述

swiss-ip-mcp 是一个 模型上下文协议（MCP） 服务，可让 AI 模型通过语言驱动的方式，结构化访问由**瑞士联邦知识产权研究所（IGE/IPI）**运营的瑞士知识产权注册数据库 Swissreg。

它是 patent-mcp 的继任项目，涵盖 Swissreg Datadelivery API 的所有可用领域：商标、专利、专利公开文本和补充保护证书（SPC/ESZ）。

此服务与模型无关。 它适用于 Claude、GPT-4、Llama 以及任何其他兼容 MCP 的客户端，而不仅限于 Claude Desktop。

---

查询示例

自然语言查询才是它的强大之处。无需手动搜索注册数据库，只需提出问题：

“苏黎世市在 IGE 注册了哪些商标？”

“‘Learning City Zurich’这个名称是否已在瑞士注册为商标？”

“过去六个月有哪些制药公司提交了瑞士专利申请？”

“列出自 2025 年 1 月以来教育领域（尼斯分类第 41 类）的所有商标申请。”

“诺华在瑞士持有哪些补充保护证书？”

---

覆盖领域

领域	说明
商标	瑞士商标注册数据库——申请、保护、所有者、尼斯分类
专利	瑞士专利——申请、授权、IPC 分类、申请人、发明人
专利公开文本	瑞士官方公报中的专利公开文本
SPC / ESZ	药品和植物保护产品的补充保护证书

注意： Swissreg Datadelivery API 目前尚不支持外观设计搜索。

---

工具（11 个）

工具	功能
swiss_ip_search_trademarks	全文商标搜索（支持通配符 *）
swiss_ip_get_trademark	根据注册号获取商标信息
swiss_ip_search_trademarks_by_owner	查找指定所有者持有的所有商标
swiss_ip_search_trademarks_by_class	按尼斯分类类别筛选商标
swiss_ip_search_patents	全文专利搜索
swiss_ip_get_patent	根据专利号获取专利信息
swiss_ip_search_patents_by_applicant	按申请人或发明人姓名查找专利
swiss_ip_search_patent_publications	搜索专利公开文本
swiss_ip_search_spc	SPC/ESZ 搜索（制药和植物保护）
swiss_ip_search_recent_filings	按日期范围筛选所有领域的申请
swiss_ip_get_quota	查看剩余 API 数据传输配额

资源与提示词

除了工具，服务器还公开了另外两种 MCP 基元：

资源（只读元数据，swissip:// URI 方案）：

URI	内容
swissip://about	服务器和数据来源元数据（来源、涵盖的域名）
swissip://domains	涵盖的 IP 域名列表

提示词（精选工作流模板）：

提示词	参数	用途
trademark_availability	name	检查名称是否为已注册的瑞士商标
competitor_ip_report	company	汇总公司的 IP 概况（商标 + 专利）
recent_ip_filings_report	ip_type, date_from, date_to	汇报某个时间段内的近期申请

错误语义

工具执行错误（API 故障、超时、缺少凭据）会通过 MCP isError: true 返回，并附带经过屏蔽、对用户友好的消息；内部详情（堆栈跟踪、原始 API 响应正文）仅写入服务器日志。查询特定编号但未找到结果不属于错误：它会返回正常结果，其中包含 match_type: "none" 和一条 message。

---

项目阶段

根据 MCP 分阶段推出模型，此服务目前处于第 1 阶段（只读）：所有工具均为只读，不会写入任何内容。有关阶段计划以及未来任何具备写入能力的阶段所需的先决条件，请参阅 ROADMAP.md。

---

架构

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

传输模式

传输方式	用例	配置
stdio	Claude Desktop、本地开发	默认（无需额外设置）
Streamable HTTP	云端部署（Render.com 等）	MCP_TRANSPORT=streamable-http
SSE	旧版 HTTP 客户端 — 已弃用	MCP_TRANSPORT=sse

SSE 已弃用。 协议修订版 2026-07-28 根据功能生命周期策略（SEP-2596）将 HTTP+SSE 传输重新归类为已弃用（它自 2025-03-26 起便已被软性弃用）。在为期 12 个月的弃用窗口内，此处仍会提供该传输方式；新的部署应使用 MCP_TRANSPORT=streamable-http。

传输方式在启动时根据 MCP_TRANSPORT 环境变量选择（默认为 stdio）。HTTP 传输由 uvicorn 提供服务，并遵循以下配置：

变量	默认值	用途
MCP_HOST	127.0.0.1	绑定地址。仅在容器内或反向代理后使用 0.0.0.0。
PORT / MCP_PORT	8000	绑定端口（优先使用 PORT，遵循 PaaS 约定）。
MCP_ALLOWED_ORIGINS	(empty)	以逗号分隔的 CORS 来源允许列表。生产环境中不得使用通配符。
MCP_ALLOWED_HOSTS	(empty)	以逗号分隔的 Host 标头允许列表；设置后可启用 DNS 重绑定防护。

Mcp-Session-Id 标头会通过 CORS 公开，以便基于浏览器的客户端读取该标头并在后续请求中回传。

---

前提条件

1. IGE 凭据（免费）：签署使用条款，并通过邮寄方式将表格寄给 IGE。IGE 收到后会发放凭据。
2. Python 3.11 或更高版本
3. uv（推荐）或 pip

---

安装

# 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]"

---

配置

环境变量

export IGE_USERNAME="your_username"
export IGE_PASSWORD="your_password"

Claude Desktop

打开配置文件：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows： %APPDATA%\Claude\claude_desktop_config.json

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

其他 MCP 客户端

swiss-ip-mcp 兼容任何支持 MCP 的客户端：

客户端	配置
Cursor	添加到 ~/.cursor/mcp.json（格式与 Claude Desktop 相同）
VS Code + Continue	通过 continue.json 中的 MCP 服务区块添加
Windsurf	通过 MCP 服务设置添加
可自托管（mcp-proxy）	使用 SSE 传输，并设置 MCP_TRANSPORT=sse

云端 / Render.com（Streamable HTTP）

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

**安全提示：**仅在容器内或反向代理后绑定到 0.0.0.0。对于公共部署，务必设置 MCP_ALLOWED_ORIGINS 和 MCP_ALLOWED_HOSTS，以启用 CORS 范围限制和 DNS 重绑定防护。此端点未经身份验证，且仅提供公共 IP 注册数据；在此传输方式后面放置需要凭据或非公开的工具之前，请先添加身份验证。

Docker / Kubernetes

项目包含经过强化的多阶段 Dockerfile（非 root UID 10001，在 /health 上执行 HEALTHCHECK）、带资源限制的 docker-compose.yml，以及 deploy/ 下的 Kubernetes 清单和 HAProxy 粘性会话配置。

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

有关加固、资源限制和扩展（无状态与粘性会话）的详情，请参阅 docs/deployment.md。

---

测试

# 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

CI 工作流在 Python 3.11、3.12 和 3.13 上运行。

---

可观测性（可选）

服务可以发出 OpenTelemetry 跟踪记录——每次工具调用对应一个 span，后端 Swissreg/IDP HTTP 调用则对应子 span。跟踪功能默认关闭，启用前不会产生额外开销。

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

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

变量	用途
MCP_OTEL_ENABLED	设置为 1 以启用跟踪导出（或只需设置下方的端点）。
OTEL_EXPORTER_OTLP_ENDPOINT	OTLP/HTTP 收集器端点（标准 OTEL 变量）。
MCP_ENV	deployment.environment 资源属性的值（默认值为 production）。

工具 span 仅携带 mcp.tool.name 和 mcp.tool.result.is_error——不会记录查询参数、凭据或响应正文。

日志记录

服务将结构化 JSON 日志写入标准错误（标准输出保留给 stdio 协议）。每次工具调用都会绑定一个 tool 名称和一个 correlation_id，因此同一次调用的所有日志行都可以关联起来。通过 LOG_LEVEL 设置级别（DEBUG / INFO / WARNING / ERROR，默认值为 INFO）：

{"event": "tool.call.start", "tool": "swiss_ip_search_trademarks", "correlation_id": "da55…", "level": "info", "timestamp": "…Z"}

---

MCP 协议版本

此服务在同一端点上支持两个协议时代。客户端在连接上发送的第一个请求决定使用哪个时代；之后来自另一个时代的声明会被拒绝。

时代	修订版本	适用对象
initialize 握手	2024-11-05 … 2025-11-25	当前客户端使用的协议。服务会以请求中的修订版本作答；如果请求要求更新的版本，则以 2025-11-25 这一上限作答。
每请求信封	2026-07-28	携带 2026-07-28 _meta 信封的请求会建立现代连接。

两个修订版本都固定在 tests/test_protocol_version.py 中，并与已安装的 SDK 进行断言校验，因此 Dependabot 升级 mcp 时，不会在无提示的情况下更改任一版本。

此外，tests/test_modern_era.py 会实际测试这两个时代：它通过组装好的 ASGI 应用发送真实请求——包含 Mcp-Method / Mcp-Protocol-Version 路由标头的 2026-07-28 _meta 信封，以及旧版 initialize——并断言返回结果。本节早先的修订版本曾声称相反的说法（“此服务不会构建 ASGI 应用来发送 initialize”），但事实从来不是这样：_build_http_app() 会构建一个 ASGI 应用，而 tests/test_cors.py 一直都在通过它发送请求。这个门禁依赖 SDK 常量，但其依据并不成立。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名——如果只针对它进行固定，当前客户端实际协商的时代就可能悄然发生变化。

服务身份

在 2026-07-28 这一版本下，服务会在每个结果的 _meta （io.modelcontextprotocol/serverInfo，SEP-2575）中标明自身身份，而不是仅在 initialize 响应中标明。该服务会在此处报告软件包版本和 websiteUrl；在测量并修复之前， 它沿用了 SDK 中默认的空 version 字符串。icons 刻意保持未设置——仓库中没有图标资源。

更新策略。 门禁检查失败时，不要盲目修改常量：请阅读两个版本修订之间的规范变更日志，确认服务仍正常运行，然后同时更新常量、本节、README.de.md 和 CHANGELOG.md。

---

数据来源

所有数据均由 IGE/IPI Swissreg Datadelivery API 提供。签署使用条款后即可免费使用该 API，但每月数据传输量受限。可随时使用 swiss_ip_get_quota 工具查看剩余配额。

字段	值
提供方	瑞士联邦知识产权局（IGE/IPI）
来源	Swissreg Datadelivery API — https://www.swissreg.ch/public/apidocs/
许可证 / 条款	IGE/IPI Swissreg Datadelivery API 使用条款

来源信息： 每个工具响应都包含一个 source 区块（提供方、来源 URL、许可证），以便下游使用方保留来源归属。结果封装格式为 { source, total, count, match_type, results, next_page_token }。

---

安全与限制

• 只读： 所有工具都会向 Swissreg API 发送经过身份验证的 POST 请求，不会在任何系统上写入、修改或删除数据。
• 无个人数据： API 返回公开的 IP 注册信息（商标名称、专利标题、申请人组织）。除了 IGE API 在公开记录中返回的内容外，本服务不会处理或存储任何个人身份信息（PII）。
• 速率限制与配额： IGE Swissreg API 对每个账户设有每月数据传输配额。请使用 swiss_ip_get_quota 工具监控剩余配额。服务对每个请求设有 60s 超时。探索性查询时，请避免使用较大的 page_size（>20）。
• 身份验证： 凭据（IGE_USERNAME、IGE_PASSWORD）在运行时从环境变量读取，绝不会记录日志或持久化。
• 服务条款： 数据受 IGE Swissreg Datadelivery API 使用条款约束。获得 API 访问权限前，必须与 IGE/IPI 签署使用协议。
• 地址列表已在无凭据的情况下验证（2026-08-08）。 本服务构建时使用的每个地址、Keycloak realm 和 client_id 都与源站发布的信息一致。结果为空——并且已将其记录为空，因为没人记录的空结果在下次检查时就不算数。进行了三项独立验证，因为单项验证不足以证明这一点：
  • IDP 能区分不同情况：对 realms/egov 使用错误凭据会返回 invalid_grant（“Invalid user credentials”）；虚构的 realm 会返回 404 “Realm does not exist”；虚构的 client_id 会返回 invalid_client。因此，realm 和 client 均存在，缺少的只有凭据。
  • realm 会在 .well-known/openid-configuration 中声明自己的 token endpoint——与此处构建的 URL 完全一致。
  • 官方 API 文档逐字列出两个地址，其中包括作为“constant string”的 client_id。
• 为何需要第三项验证： Swissreg API 本身无法区分。不带 token 的 POST 会返回 403，带虚构 token 的 POST 会返回 401——而 /public/api/ 下随意编造的路径也会返回完全相同的结果。因此，状态码无法证明任何事情。scripts/record_fixtures.py 每次运行时都会重新测量这一点，并在对照项无法区分时中止。
• 自 2026-10-04 起已记录响应负载（tests/fixtures/live/，并附有自己的 RECORDING.md）：结构真实，文本值为合成内容。凭据到位之前，这些内容都标记为 NOT RECORDED，而这一缺口造成了代价。手写的 fixture 将记录元素命名为 Item，将计数器命名为 TotalCount——恰好与解析器所查找的名称一致。但源站用的两个名称都不是这些：记录是带有 role="item" 的 Result 子元素，计数器是 Meta/TotalItemCount。两处错误如出一辙，因此所有搜索工具都返回零条结果，而 171 个单元测试仍全部通过。此情况在运行 37198882345 和 37201829767 中测得。
• 不作保证： 本服务是社区项目，与瑞士联邦知识产权研究所（IGE/IPI）无关联。服务可用性取决于上游 API 的运行时间。

---

相关服务

服务	内容
zurich-opendata-mcp	苏黎世市开放数据（CKAN、天气、停车、地理数据）
fedlex-mcp	通过 Fedlex SPARQL 获取瑞士联邦法律
swiss-transport-mcp	公共交通、运营中断、车票、列车编组
swiss-road-mobility-mcp	共享出行、电动汽车充电站、交通数据
global-education-mcp	UNESCO / OECD 教育数据
patent-mcp	⚠️ 已弃用——已由本服务取代

---

贡献

如何报告错误和提交更改，请参阅 CONTRIBUTING.md（Deutsch）。

---

安全

有关安全态势、加固摘要以及如何报告漏洞，请参阅 SECURITY.md。

---

许可证

MIT 许可证 — 请参阅 LICENSE

---

作者

Hayal Oezkan · github.com/malkreide

安装

通过 uv 的 uvx 运行 — 无需克隆或手动安装。将其添加到 MCP 客户端配置中（Claude Desktop、Cursor 和 Windsurf 使用 mcpServers；VS Code 在 .vscode/mcp.json 中使用顶层 servers 键）：

{
  "mcpServers": {
    "swiss-ip-mcp": {
      "command": "uvx",
      "args": [
        "swiss-ip-mcp"
      ],
      "env": {
        "IGE_USERNAME": "<your IGE_USERNAME>",
        "IGE_PASSWORD": "<your IGE_PASSWORD>"
      }
    }
  }
}

需要凭据：设置 IGE_USERNAME、IGE_PASSWORD（替换上方的占位值）。