io.github.malkreide/eth-library-mcp

🇨🇭 Part of the Swiss Public Data MCP Portfolio

🏛️ eth-library-mcp

🌐 English | Deutsch

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

Variable	Description	Required
ETH_LIBRARY_API_KEY	API key for the Discovery API	✅
ETH_LIBRARY_LOG_LEVEL	Log level (DEBUG/INFO/WARNING/ERROR), default INFO	—
ETH_LIBRARY_CORS_ORIGINS	Comma-separated CORS allow-origins for --http. Empty by default: no browser client is permitted. * allows any origin and is logged as a warning. Does not affect stdio clients.	—
ETH_LIBRARY_ALLOWED_HOSTS	Comma-separated hostnames this server is reachable under. Required for a non-loopback bind (--host 0.0.0.0): the process cannot derive its own public name, and without this the SDK answers 421 Invalid Host header to every request. Empty by default; loopback stays reachable either way.	—

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)

Tool	Description
eth_search_resources	Full-text search over 30M+ resources with fields, operators, facets
eth_get_resource	Full metadata for a specific resource via MMS-ID
eth_search_archive	Search within a specific archive (University Archives, Max Frisch, Thomas Mann, etc.)
eth_search_by_type	Filter by resource type (books, maps, images, archival material, etc.)
eth_search_education	Curated search for education topics (pedagogy, school history, etc.)

Utilities

Tool	Description
eth_library_info	Server overview: all types and archives at a glance

Resources & Prompts

Item	Type	Description
eth://resource-types	Resource	All available resource types
eth://archives	Resource	All available archives and collections
research-workflow	Prompt	Structured research workflow
education-research	Prompt	Education topics workflow (Schulamt-optimised)

Query Syntax

The Discovery API uses structured queries:

field,operator,value

Field	Meaning
any	All fields (recommended for starters)
title	Title only
creator	Author / creator
sub	Subject headings / topics

Operator	Meaning
contains	Term is present
exact	Exact match
begins_with	Starts with

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

Identifier	Description
ETH_Hochschularchiv	Institutional memory of ETH Zurich
ETH_MaxFrischArchiv	Estate of Swiss author Max Frisch
ETH_ThomasMannArchiv	Letters and documents of Thomas Mann
ETH_GraphischeSammlung	Prints, drawings, graphic works
ETH_Bildarchiv	Science/technology history, Swissair (E-Pics)

Example Use Cases

Query	Tool
"Find books about Zurich school history"	eth_search_education
"What's in the Max Frisch archive?"	eth_search_archive
"Find historical maps of Switzerland"	eth_search_by_type
"Get full metadata for resource ID 991170525863705501"	eth_get_resource
"Which archives does the ETH Library hold?"	eth_library_info

---

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.

Era	Revision	Who reaches it
initialize handshake	2024-11-05 … 2025-11-25	What today's clients speak. The server answers with the revision asked for, or with the 2025-11-25 ceiling when the request asks for something newer.
Per-request envelope	2026-07-28	A request carrying the 2026-07-28 _meta envelope opens a modern connection.

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:

Field	Value	Source
name	eth-library-mcp	the programmatic identifier — the same string as the distribution name in pyproject.toml, packages[0].identifier in server.json and the suffix of the registry name io.github.malkreide/eth-library-mcp. It used to read eth_library_mcp, the module path: a name under which this server is available nowhere.
title	ETH-Bibliothek Zürich	SERVER_TITLE in server.py — the only value with no source outside
version	the installed distribution's version	importlib.metadata, so it cannot drift from pyproject.toml
description	the distribution summary	importlib.metadata
websiteUrl	the Homepage project URL	importlib.metadata

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

Measured, not read back, in tests/test_server_identity.py: the assertions drive a real modern POST through build_http_app(). A look at mcp.version would stay green even if the constructor argument were lost or the SDK stopped stamping at all.

---

Testing

# 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

Until 2026-08-08 this repository had no live tests at all — pytest -m live collected zero. Nothing in it had ever been held against the source.

The Discovery payloads still cannot be recorded: the API requires a key, and tests/fixtures/PROVENANCE.md lists them explicitly as NOT RECORDED rather than giving them a date they never had. What is recordable is the contract the source gives up without a key — which routes the gateway serves — and that is exactly what the finding hangs on. The two control_* entries are part of the measurement, not decoration: without them the recording only proves that someone got a 404; with them it proves what the gateway distinguishes.

The two live tests need no key and say something anyway: they report if the Persons API comes back (then the tool should return) or if Discovery loses its route (then five tools are affected).

---

Safety & Limits

• Read-only: All tools perform HTTP GET requests only — no data is written, modified, or deleted.
• No personal data: The APIs return bibliographic metadata (titles, authors, subjects, identifiers). No personally identifiable information (PII) is processed or stored by this server.
• Authentication: A free API key from developer.library.ethz.ch is required. The key is read from the ETH_LIBRARY_API_KEY environment variable and never logged or transmitted to third parties.
• Rate limits: The ETH Library API enforces rate limits per API key. The server enforces a 30-second timeout per request. Use limit and offset parameters conservatively.
• Data freshness: Results reflect the ETH Library catalogue at query time. No caching is performed by this server.
• Terms of service: Bibliographic metadata is published as Public Domain — free for all uses. API access is subject to the ETH Library Developer Portal terms.
• No guarantees: This is a community project, not affiliated with the ETH Library or ETH Zurich. Availability depends on upstream APIs.

---

Contributing

Contributions are welcome! See CONTRIBUTING.md (Deutsch) for guidelines.

---

Security

Read-only, no PII, a single upstream API key, and a fixed egress allow-list of ETH Library endpoints. See SECURITY.md (Deutsch) for the full security posture and accepted-risk decisions.

---

Changelog

See CHANGELOG.md

---

License

• Server code: MIT License — see LICENSE
• Bibliographic metadata: Public Domain (no restrictions)
• API documentation: developer.library.ethz.ch

---

Author

Hayal Oezkan · github.com/malkreide

---

Powered by Model Context Protocol • 1 API • 6 Tools • 2 Resources • 2 Prompts

Installation

Run via uv's uvx — no clone or manual install needed. Add to your MCP client config (mcpServers for Claude Desktop, Cursor and Windsurf; use a top-level servers key for VS Code in .vscode/mcp.json):

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