Eth Library

🇨🇭 Part of the Swiss Public Data MCP Portfolio

🏛️ eth-library-mcp

License: MIT Python 3.11+ MCP Data Source CI

🌐 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 Discovery & Persons 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.	—

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

Persons API

Tool	Description

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.

---

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