eth-library-mcp

🇨🇭 スイス公共データ MCP ポートフォリオの一部です

🏛️ eth-library-mcp

🌐 英語 | ドイツ語

AI モデルがチューリッヒの ETH 図書館にある3,000万点以上のリソース（書籍、地図、画像、アーカイブ資料）に直接アクセスできる MCP サーバーです。

デモ

---

概要

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 図書館のアーカイブで、チューリッヒの学校の歴史に関する歴史的文書を探してください。」

---

機能

• 🔍 全文検索：フィールド、演算子、ファセットを使って3,000万点以上のリソースを検索
• 📖 リソース詳細：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 が組み込まれていないため、同じ LAN 上の誰でもツールを呼び出せます。

💡 「開発者のノートパソコンでは stdio、ブラウザーでは HTTP — プロキシ経由で。」

---

利用可能なツール

Discovery API（api.library.ethz.ch）

ツール	説明
eth_search_resources	フィールド、演算子、ファセットを指定して、3,000 万件以上のリソースを全文検索します
eth_get_resource	MMS-ID を指定して、特定のリソースの完全なメタデータを取得します
eth_search_archive	特定のアーカイブ内を検索します（University Archives、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 Protocol Version

このサーバーは、同じエンドポイントで2つのプロトコル時代に対応しています。接続時のクライアントからの最初のリクエストによって適用される時代が決まり、後から別の時代を指定しても拒否されます。

時代	リビジョン	対応するクライアント
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 はハンドシェイク時代ではなく、モダン時代の別名である点に注意してください。これだけを基準に固定すると、現在のクライアントが実際にネゴシエートする時代が変更可能なままになります。

更新方針。 ゲートに失敗したときは、定数を安易に編集しないでください。2つのリビジョン間の仕様変更履歴を確認し、サーバーが引き続き正常に動作することを検証したうえで、定数、このセクション、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 を実行しても、テストは1件も収集されませんでした。ソースに照らして検証されたものは、これまで何もありませんでした。

Discovery のペイロードは、引き続き記録できません。API にはキーが必要であり、 tests/fixtures/PROVENANCE.md では、実際には存在しない日付を付けるのではなく、 明示的に未記録とされています。記録できるのは、キーなしでソースから明らかになる契約、つまり ゲートウェイがどのルートを提供するかであり、調査結果の根拠もまさにそこにあります。2つの control_* エントリは測定の一部であり、飾りではありません。これらがなければ、記録から分かるのは誰かが 404 を受け取ったことだけですが、これらがあればゲートウェイが何を区別しているかを証明できます。

2つのライブテストにはキーが不要で、それぞれ意味のある結果を報告します。Persons API が復旧した場合はそのツールが動作するはずであること、Discovery のルートが失われた場合は5つのツールに影響することを報告します。

---

安全性と制限

• **読み取り専用：**すべてのツールは 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（ドイツ語）をご覧ください。

---

セキュリティ

読み取り専用、PII なし、上流 API キーは1つのみ、ETH Library エンドポイントへの送信先を限定する固定の許可リストを採用しています。セキュリティ対策の全容と、受け入れているリスクに関する判断については、SECURITY.md（ドイツ語）をご覧ください。

---

変更履歴

CHANGELOG.mdをご覧ください。

---

ライセンス

• **サーバーコード：**MIT License — LICENSEをご覧ください。
• **書誌メタデータ：**パブリックドメイン（制限なし）
• API ドキュメント：developer.library.ethz.ch

---

作者

Hayal Oezkan · github.com/malkreide

---

Model Context Protocol を利用 • API 1件 • ツール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"
      ]
    }
  }
}