eth-library-mcp

🇨🇭 属于 Swiss Public Data MCP Portfolio

🏛️ eth-library-mcp

🌐 English | Deutsch

一个 MCP 服务，可让 AI 模型直接访问苏黎世 ETH 图书馆的 3000 多万条资源，包括图书、地图、图片和档案资料。

演示

---

概述

eth-library-mcp 将 Claude 等 AI 助手连接到瑞士最大的自然科学图书馆。它通过 ETH 图书馆的 Discovery API 提供全文搜索、档案级查询和资源类型筛选，并通过一个标准化的 MCP 接口访问。

6 个工具 · 1 个 API · 2 个资源 · 2 个提示词

MCP 协议版本： 2026-07-28（通过 mcp[cli]>=2.0.0,<3）。

BUG-02 已解决——方法是移除该工具。 文档曾将 eth_search_persons 标注为“当前无法使用，正确的 URL 有待核实”。现已完成核实，结论是：没有正确的 URL。Persons API 已从网关中消失，而不只是被锁定。网关会在检查 API 密钥之前进行路由，因此已有的路由会返回 401，缺失的路由则返回 404——/discovery/v1/resources 返回 401，所有 /persons/v1/* 路径都返回 404，作为对照测试，特意编造的 Discovery 路径也返回 404。提供一个根本不可能存在的功能，与返回空结果一样是个错误，只是后果更明显。测量结果已记录并注明日期，见 tests/fixtures/api_routes.json。

演示示例查询： “查找 ETH 图书馆档案中有关苏黎世学校历史的历史文献。”

---

功能

• 🔍 全文搜索：搜索 3000 多万条资源，支持字段、运算符和分面
• 📖 资源详情：通过 MMS-ID 获取完整元数据
• 🗂️ 档案搜索：ETH 大学档案馆、Max Frisch、Thomas Mann、Graphische Sammlung、Bildarchiv
• 🏷️ 资源类型筛选：图书、地图、图片、档案资料等
• 🎓 教育搜索：面向教学法和学校历史优化的精选工作流
• 📋 服务概览：一览所有资源类型和档案馆
• 🗣️ 内置提示词：结构化研究和教育研究工作流
• ☁️ 双传输方式：供 Claude Desktop 使用的 stdio，以及用于云部署的 Streamable HTTP/SSE

---

前提条件

• Python 3.11+
• 从 developer.library.ethz.ch 获取的免费 API 密钥

---

安装

# Clone the repository
git clone https://github.com/malkreide/eth-library-mcp.git
cd eth-library-mcp

# Install
pip install -e .

# Or with uv (recommended)
uv pip install -e .

---

快速开始

# Set the API key
export ETH_LIBRARY_API_KEY=your_key_here   # macOS / Linux
# $env:ETH_LIBRARY_API_KEY = "your_key_here"  # Windows (PowerShell)

# Start the server (stdio mode for Claude Desktop)
python -m eth_library_mcp.server

如果没有 API 密钥，服务会返回包含注册链接的实用错误消息，不会崩溃。

立即在 Claude Desktop 中试用：

“查找有关瑞士教育史的 ETH 图书馆藏书。” “在 Max Frisch 档案中搜索有关苏黎世的手稿。”

→ 按受众查看更多使用场景 →

---

配置

环境变量

变量	描述	必填
ETH_LIBRARY_API_KEY	Discovery API 的 API 密钥	✅
ETH_LIBRARY_LOG_LEVEL	日志级别（DEBUG/INFO/WARNING/ERROR），默认为 INFO	—
ETH_LIBRARY_CORS_ORIGINS	以逗号分隔的 --http CORS 允许来源列表。默认为空：不允许浏览器客户端。* 表示允许任何来源，并会记录警告。不影响 stdio 客户端。	—
ETH_LIBRARY_ALLOWED_HOSTS	以逗号分隔的可访问此服务的主机名。绑定到非环回地址（--host 0.0.0.0）时必填：进程无法推导自己的公网名称；如果未设置此变量，SDK 会对每个请求返回 421 Invalid Host header。默认为空；无论是否设置，环回地址都可访问。	—

Claude Desktop 配置

{
  "mcpServers": {
    "eth-library": {
      "command": "python",
      "args": ["-m", "eth_library_mcp.server"],
      "env": {
        "ETH_LIBRARY_API_KEY": "your_key_here"
      }
    }
  }
}

配置文件位置：

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

云端部署（供浏览器访问的 SSE）

通过浏览器中的 claude.ai 使用（例如，在未安装本地软件的受管工作站上）：

python -m eth_library_mcp.server --http --port 8000

HTTP 传输默认绑定到 127.0.0.1。若要将其开放到其他网络接口， 请显式传入 --host：

# Only behind a reverse-proxy / firewall that terminates TLS and enforces auth.
python -m eth_library_mcp.server --http --host 0.0.0.0 --port 8000

⚠️ 请勿在没有反向代理的情况下绑定到 0.0.0.0。 服务没有 内置身份验证、速率限制或 TLS——局域网中的任何邻居都可以调用你的工具。

💡 “开发者笔记本用 stdio，浏览器用 HTTP——通过代理访问。”

---

可用工具

Discovery API（api.library.ethz.ch）

工具	描述
eth_search_resources	对 3,000 多万个资源进行全文搜索，支持字段、运算符和分面
eth_get_resource	通过 MMS-ID 获取特定资源的完整元数据
eth_search_archive	在指定档案中搜索（大学档案、Max Frisch、Thomas Mann 等）
eth_search_by_type	按资源类型筛选（书籍、地图、图像、档案资料等）
eth_search_education	针对教育主题的精选搜索（教育学、学校史等）

实用工具

工具	描述
eth_library_info	服务概览：一览所有类型和档案

资源与提示词

项目	类型	描述
eth://resource-types	资源	所有可用的资源类型
eth://archives	资源	所有可用的档案和馆藏
research-workflow	提示词	结构化研究工作流
education-research	提示词	教育主题工作流（针对 Schulamt 优化）

查询语法

Discovery API 使用结构化查询：

field,operator,value

字段	含义
any	所有字段（推荐入门使用）
title	仅标题
creator	作者／创作者
sub	主题标题／主题

运算符	含义
contains	包含该词
exact	精确匹配
begins_with	以该词开头

示例：

any,contains,Volksschule Zürich
title,contains,Pädagogik
creator,exact,Einstein Albert
sub,contains,Bildungsforschung
title,contains,Schule;sub,contains,Geschichte

可用档案

标识符	描述
ETH_Hochschularchiv	ETH Zurich 的机构记忆
ETH_MaxFrischArchiv	瑞士作家 Max Frisch 的遗产
ETH_ThomasMannArchiv	Thomas Mann 的信件和文件
ETH_GraphischeSammlung	版画、素描、图形作品
ETH_Bildarchiv	科学／技术史、Swissair（E-Pics）

使用示例

查询	工具
“查找有关苏黎世学校史的书籍”	eth_search_education
“Max Frisch 档案中有什么？”	eth_search_archive
“查找瑞士历史地图”	eth_search_by_type
“获取资源 ID 991170525863705501 的完整元数据”	eth_get_resource
“ETH Library 收藏了哪些档案？”	eth_library_info

---

项目结构

eth-library-mcp/
├── src/
│   └── eth_library_mcp/
│       ├── __init__.py        # Package init, version
│       └── server.py          # FastMCP server, all tools
├── tests/
│   └── test_server.py         # Unit tests
├── CHANGELOG.md
├── CONTRIBUTING.md             # Contribution guide (English)
├── CONTRIBUTING.de.md          # Contribution guide (German)
├── SECURITY.md                 # Security posture (English)
├── SECURITY.de.md              # Security posture (German)
├── LICENSE
├── README.md                  # This file (English)
├── README.de.md               # German version
├── claude_desktop_config.json # Example Claude Desktop configuration
└── pyproject.toml             # Build configuration

---

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 时不会悄然更改其中任何一个。握手上限是通过组装后的 ASGI 堆栈执行实时 initialize 测得的，而不是从常量名称中读取。

请注意，SDK 的 LATEST_PROTOCOL_VERSION 是现代时代的别名，而非握手时代的别名——若仅以它为准，当前客户端实际协商的时代仍会任意漂移。

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

服务身份（serverInfo）

2026-07-28 会将服务的 Implementation 块写入每个现代结果的 _meta.io.modelcontextprotocol/serverInfo 中（规范 #3002）——较早的修订版本只会在 initialize 结果中携带该信息。原本只出现一次的字段现在会在每次调用中重复出现，而且 version 是必填项。

SDK 不会填充其中任何字段：*"未声明版本的服务会报告空的 version；SDK 不会用自身版本代替。" *通过组装后的 ASGI 堆栈测得，此服务在两个时代中此前均会返回 "version": ""，而 server.json 却告知注册表版本为 0.3.4。现在它声明：

字段	值	来源
name	eth-library-mcp	程序化标识符——与 pyproject.toml 中的发行包名称、server.json 中的 packages[0].identifier 以及注册表名称 io.github.malkreide/eth-library-mcp 的后缀相同。此前它是 eth_library_mcp，也就是模块路径；该服务并未以这个名称在任何地方提供。
title	ETH-Bibliothek Zürich	server.py 中的 SERVER_TITLE——唯一没有外部来源的值
version	已安装发行包的版本	importlib.metadata，因此不会与 pyproject.toml 中的版本发生偏差
description	发行包摘要	importlib.metadata
websiteUrl	Homepage 项目 URL	importlib.metadata

icons 保持未设置：此代码库没有提供任何图标，虚构路径会声称存在一个实际不存在的文件。

tests/test_server_identity.py 中的测试结果是实测而非读取回来的：这些断言会通过 build_http_app() 发送真实的现代 POST 请求。仅查看 mcp.version 即使构造函数参数丢失或 SDK 不再写入相关信息，测试仍会通过。

---

测试

# Unit tests (no API key required)
PYTHONPATH=src pytest tests/ -m "not live"

# Integration tests (API key required)
# Live checks against the gateway — these need NO API key
PYTHONPATH=src pytest tests/ -m "live"

# Re-record the route census (writes tests/fixtures/PROVENANCE.md)
python scripts/record_fixtures.py

截至 2026-08-08，本仓库完全没有实时测试——运行 pytest -m live 收集到的测试数量为 0。仓库中的内容从未与源代码进行过核对。

Discovery 负载仍无法记录：该 API 需要密钥，而 tests/fixtures/PROVENANCE.md 明确将它们列为未记录，而不是给它们标上一个从未有过的日期。可以记录的是源代码在没有密钥时所揭示的契约——网关提供哪些路由——这也正是这一发现的依据。两个 control_* 条目是测量的一部分，不是装饰：没有它们，记录只能证明有人收到了 404；有了它们，才能证明网关区分了什么。

这两个实时测试无需密钥，也能说明一些情况：它们会报告 Persons API 是否恢复（若恢复，工具就应该返回），或 Discovery 是否失去其路由（若失去，则会影响五个工具）。

---

安全与限制

• 只读： 所有工具仅执行 HTTP GET 请求，不会写入、修改或删除任何数据。
• 无个人数据： API 返回的是书目元数据（标题、作者、主题、标识符）。此服务不会处理或存储任何个人身份信息（PII）。
• 身份验证： 需要从 developer.library.ethz.ch 获取免费的 API 密钥。密钥从 ETH_LIBRARY_API_KEY 环境变量中读取，绝不会记录日志或传输给第三方。
• 速率限制： ETH Library API 会对每个 API 密钥施加速率限制。服务会为每个请求设置 30 秒超时。请谨慎使用 limit 和 offset 参数。
• 数据时效性： 结果反映查询时 ETH Library 目录中的内容。本服务不执行缓存。
• 服务条款： 书目元数据以公共领域形式发布，可免费用于任何用途。API 访问须遵守 ETH Library Developer Portal 条款。
• 不作保证： 这是一个社区项目，与 ETH Library 或 ETH Zurich 没有关联。服务可用性取决于上游 API。

---

贡献

欢迎贡献！请参阅 CONTRIBUTING.md（Deutsch）了解相关指南。

---

安全

本服务只读、不处理 PII，仅使用一个上游 API 密钥，并固定出站流量允许列表，只包含 ETH Library 端点。完整的安全状况和已接受风险的决策请参阅 SECURITY.md（Deutsch）。

---

更新日志

请参阅 CHANGELOG.md

---

许可证

• 服务端代码： MIT License——请参阅 LICENSE
• 书目元数据： 公共领域（不受限制）
• API 文档： developer.library.ethz.ch

---

作者

Hayal Oezkan · github.com/malkreide

---

由 Model Context Protocol 提供支持 • 1 个 API • 6 个工具 • 2 个资源 • 2 个提示词

安装

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

{
  "mcpServers": {
    "eth-library-mcp": {
      "command": "uvx",
      "args": [
        "eth-library-mcp"
      ]
    }
  }
}