Eth Library MCP

🇨🇭 Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)

🏛️ eth-library-mcp

🌐 English | [Deutsch](README.de.md)

MCP server giving AI models direct access to 30M+ resources at ETH Library Zurich – books, maps, images and archival material.

Demo

---

Overview

eth-library-mcp connects AI assistants like Claude to the largest natural-science library in Switzerland. It exposes full-text search, archive-level queries and resource-type filtering via the ETH Library's Discovery API – all through a single, standardised MCP interface.

6 Tools · 1 API · 2 Resources · 2 Prompts

MCP Protocol Version: 2026-07-28 (via mcp[cli]>=2.0.0,<3).

BUG-02 is resolved — by removing the tool. eth_search_persons was documented

as "currently non-functional, correct URL to be verified". It has now been verified,

and there is no correct URL: the Persons API is gone from the gateway, not merely

locked. The gateway routes *before* it checks the API key, so an existing route

answers 401 and a missing one answers 404 — /discovery/v1/resources gives 401,

every /persons/v1/* path gives 404, and so does a deliberately invented Discovery

path used as a control. Offering a capability that cannot exist is the same mistake as

returning an empty result, only louder. The measurement is recorded and dated in

tests/fixtures/api_routes.json.

Anchor demo query: *"Find historical documents about Zurich school history in the ETH Library archives."*

---

Features

• 🔍 Full-text search over 30M+ resources with fields, operators, and facets
• 📖 Resource details – full metadata via MMS-ID
• 🗂️ Archive search – ETH University Archives, Max Frisch, Thomas Mann, Graphische Sammlung, Bildarchiv
• 🏷️ Resource type filter – books, maps, images, archival material and more
• 🎓 Education search – curated workflow optimised for pedagogy and school history
• 📋 Server overview – all resource types and archives at a glance
• 🗣️ Built-in prompts – structured research and education-research workflows
• ☁️ Dual transport – stdio for Claude Desktop, Streamable HTTP/SSE for cloud deployment

---

Prerequisites

• Python 3.11+
• A free API key from developer.library.ethz.ch

---

Installation

# 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 .

---

Quickstart

# 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

Without an API key the server returns a helpful error message with the registration link – no crashes.

Try it immediately in Claude Desktop:

*"Find books about Swiss education history in the ETH Library."*

*"Search the Max Frisch archive for manuscripts about Zurich."*

→ More use cases by audience →

---

Configuration

Environment Variables

Claude Desktop Configuration

{

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

Config file locations:

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

Cloud Deployment (SSE for browser access)

For use via claude.ai in the browser (e.g. on managed workstations without local software):

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

The HTTP transport binds to 127.0.0.1 by default. To expose it on another interface, pass --host explicitly:

# 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

⚠️ Do not bind to `0.0.0.0` without a reverse proxy. The server has no

built-in auth, rate-limiting or TLS — any LAN neighbour could call your tools.

💡 *"stdio for the developer laptop, HTTP for the browser — behind a proxy."*

---

Available Tools

Discovery API (api.library.ethz.ch)

Utilities

Resources & Prompts

Query Syntax

The Discovery API uses structured queries:

field,operator,value

Examples:

any,contains,Volksschule Zürich

title,contains,Pädagogik creator,exact,Einstein Albert sub,contains,Bildungsforschung title,contains,Schule;sub,contains,Geschichte

Available Archives

Example Use Cases

---

Project Structure

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

This server speaks two protocol eras over the same endpoint. The client's first request on a connection decides which one applies; a later claim from the other era is refused.

Both revisions are pinned in tests/test_protocol_version.py and asserted against the installed SDK, so a Dependabot bump of mcp cannot move either one silently. The handshake ceiling is measured against a live initialize through the assembled ASGI stack, not read off a constant name.

Note that the SDK's LATEST_PROTOCOL_VERSION is an alias for the modern era, not for the handshake era — pinning against it alone would leave the era that current clients actually negotiate free to drift.

Update policy. When the gate fails, do not edit the constant blindly: read the spec changelog between the two revisions, verify the server still behaves, then move the constant, this section, README.de.md and CHANGELOG.md together.

Server identity (serverInfo)

2026-07-28 stamps the server's Implementation block into every modern result under _meta.io.modelcontextprotocol/serverInfo (spec #3002) — earlier revisions carried it only in the initialize result. What used to be a one-time field is now repeated on every call, and version is required.

The SDK fills none of it: *"An unversioned server reports an empty version; the SDK never substitutes its own."* Measured against the assembled ASGI stack, this server used to answer "version": "" in both eras while server.json told the registry 0.3.4. It now declares:

icons stays unset: this repository ships none, and an invented path would assert a file that does not exist.

M