io.github.malkreide/eth-library-mcp
ETH Library Discovery and Persons APIs
Open source Open in the app JSON README (API)
About
ETH Library Discovery and Persons APIs
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- malkreide
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.3.4
- Stars
- 1
- Open pull requests
- 1
- Last push
- 2026-09-01T00:31:39Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:27
- Updated
- 2026-08-29 04:00:27
- Origin id
io.github.malkreide/eth-library-mcp
README
> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**
# 🏛️ eth-library-mcp
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://modelcontextprotocol.io/)
[](https://developer.library.ethz.ch)
[](https://github.com/malkreide/eth-library-mcp/actions/workflows/ci.yml)
🌐 **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`](https://modelcontextprotocol.io/specification/) (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`](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](https://developer.library.ethz.ch)
---
## Installation
```bash
# 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
```bash
# 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 →](EXAMPLES.md)
---
## 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. | — |
| `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
```json
{
"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):
```bash
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:
```bash
# 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`](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`](CHANGELOG.md) together.
---
## Testing
```bash
# 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](https://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](https://developer.library.ethz.ch) 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](CONTRIBUTING.md) ([Deutsch](CONTRIBUTING.de.md)) 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](SECURITY.md) ([Deutsch](SECURITY.de.md))
for the full security posture and accepted-risk decisions.
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md)
---
## License
- **Server code:** MIT License — see [LICENSE](LICENSE)
- **Bibliographic metadata:** Public Domain (no restrictions)
- **API documentation:** [developer.library.ethz.ch](https://developer.library.ethz.ch)
---
## Author
**Hayal Oezkan** · [github.com/malkreide](https://github.com/malkreide)
---
*Powered by [Model Context Protocol](https://modelcontextprotocol.io/) • 1 API • 6 Tools • 2 Resources • 2 Prompts*
<!-- mcp-name: io.github.malkreide/eth-library-mcp -->
<!-- BEGIN GENERATED: install -->
## Installation
Run via [`uv`](https://docs.astral.sh/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`):
```json
{
"mcpServers": {
"eth-library-mcp": {
"command": "uvx",
"args": [
"eth-library-mcp"
]
}
}
}
```
<!-- END GENERATED: install -->