{
  "markdown": "> 🇨🇭 **Part of the [Swiss Public Data MCP Portfolio](https://github.com/malkreide)**\n\n# 🏛️ eth-library-mcp\n\n![Version](https://img.shields.io/badge/version-0.3.4-blue)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io/)\n[![Data Source](https://img.shields.io/badge/Data-ETH%20Library%20Zurich-red)](https://developer.library.ethz.ch)\n[![CI](https://github.com/malkreide/eth-library-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/malkreide/eth-library-mcp/actions/workflows/ci.yml)\n\n🌐 **English** | **[Deutsch](README.de.md)**\n\n> MCP server giving AI models direct access to 30M+ resources at ETH Library Zurich – books, maps, images and archival material.\n\n### Demo\n\n![Demo: Claude using eth_search_archive to find historical school documents](docs/assets/demo.svg)\n\n---\n\n## Overview\n\n**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.\n\n**6 Tools · 1 API · 2 Resources · 2 Prompts**\n\n**MCP Protocol Version:** [`2026-07-28`](https://modelcontextprotocol.io/specification/) (via `mcp[cli]>=2.0.0,<3`).\n\n> **BUG-02 is resolved — by removing the tool.** `eth_search_persons` was documented\n> as \"currently non-functional, correct URL to be verified\". It has now been verified,\n> and there is no correct URL: the Persons API is **gone from the gateway**, not merely\n> locked. The gateway routes *before* it checks the API key, so an existing route\n> answers `401` and a missing one answers `404` — `/discovery/v1/resources` gives 401,\n> every `/persons/v1/*` path gives 404, and so does a deliberately invented Discovery\n> path used as a control. Offering a capability that cannot exist is the same mistake as\n> returning an empty result, only louder. The measurement is recorded and dated in\n> [`tests/fixtures/api_routes.json`](tests/fixtures/api_routes.json).\n\n**Anchor demo query:** *\"Find historical documents about Zurich school history in the ETH Library archives.\"*\n\n---\n\n## Features\n\n- 🔍 **Full-text search** over 30M+ resources with fields, operators, and facets\n- 📖 **Resource details** – full metadata via MMS-ID\n- 🗂️ **Archive search** – ETH University Archives, Max Frisch, Thomas Mann, Graphische Sammlung, Bildarchiv\n- 🏷️ **Resource type filter** – books, maps, images, archival material and more\n- 🎓 **Education search** – curated workflow optimised for pedagogy and school history\n- 📋 **Server overview** – all resource types and archives at a glance\n- 🗣️ **Built-in prompts** – structured research and education-research workflows\n- ☁️ **Dual transport** – stdio for Claude Desktop, Streamable HTTP/SSE for cloud deployment\n\n---\n\n## Prerequisites\n\n- Python 3.11+\n- A free API key from [developer.library.ethz.ch](https://developer.library.ethz.ch)\n\n---\n\n## Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/malkreide/eth-library-mcp.git\ncd eth-library-mcp\n\n# Install\npip install -e .\n\n# Or with uv (recommended)\nuv pip install -e .\n```\n\n---\n\n## Quickstart\n\n```bash\n# Set the API key\nexport ETH_LIBRARY_API_KEY=your_key_here   # macOS / Linux\n# $env:ETH_LIBRARY_API_KEY = \"your_key_here\"  # Windows (PowerShell)\n\n# Start the server (stdio mode for Claude Desktop)\npython -m eth_library_mcp.server\n```\n\n> Without an API key the server returns a helpful error message with the registration link – no crashes.\n\nTry it immediately in Claude Desktop:\n\n> *\"Find books about Swiss education history in the ETH Library.\"*\n> *\"Search the Max Frisch archive for manuscripts about Zurich.\"*\n\n[→ More use cases by audience →](EXAMPLES.md)\n\n---\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Description | Required |\n|---|---|---|\n| `ETH_LIBRARY_API_KEY` | API key for Discovery & Persons API | ✅ |\n| `ETH_LIBRARY_LOG_LEVEL` | Log level (`DEBUG`/`INFO`/`WARNING`/`ERROR`), default `INFO` | — |\n| `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. | — |\n| `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. | — |\n\n### Claude Desktop Configuration\n\n```json\n{\n  \"mcpServers\": {\n    \"eth-library\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"eth_library_mcp.server\"],\n      \"env\": {\n        \"ETH_LIBRARY_API_KEY\": \"your_key_here\"\n      }\n    }\n  }\n}\n```\n\n**Config file locations:**\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n### Cloud Deployment (SSE for browser access)\n\nFor use via **claude.ai in the browser** (e.g. on managed workstations without local software):\n\n```bash\npython -m eth_library_mcp.server --http --port 8000\n```\n\nThe HTTP transport binds to `127.0.0.1` by default. To expose it on another\ninterface, pass `--host` explicitly:\n\n```bash\n# Only behind a reverse-proxy / firewall that terminates TLS and enforces auth.\npython -m eth_library_mcp.server --http --host 0.0.0.0 --port 8000\n```\n\n> ⚠️ **Do not bind to `0.0.0.0` without a reverse proxy.** The server has no\n> built-in auth, rate-limiting or TLS — any LAN neighbour could call your tools.\n\n> 💡 *\"stdio for the developer laptop, HTTP for the browser — behind a proxy.\"*\n\n---\n\n## Available Tools\n\n### Discovery API (api.library.ethz.ch)\n\n| Tool | Description |\n|---|---|\n| `eth_search_resources` | Full-text search over 30M+ resources with fields, operators, facets |\n| `eth_get_resource` | Full metadata for a specific resource via MMS-ID |\n| `eth_search_archive` | Search within a specific archive (University Archives, Max Frisch, Thomas Mann, etc.) |\n| `eth_search_by_type` | Filter by resource type (books, maps, images, archival material, etc.) |\n| `eth_search_education` | Curated search for education topics (pedagogy, school history, etc.) |\n\n### Persons API\n\n| Tool | Description |\n|---|---|\n\n### Utilities\n\n| Tool | Description |\n|---|---|\n| `eth_library_info` | Server overview: all types and archives at a glance |\n\n### Resources & Prompts\n\n| Item | Type | Description |\n|---|---|---|\n| `eth://resource-types` | Resource | All available resource types |\n| `eth://archives` | Resource | All available archives and collections |\n| `research-workflow` | Prompt | Structured research workflow |\n| `education-research` | Prompt | Education topics workflow (Schulamt-optimised) |\n\n### Query Syntax\n\nThe Discovery API uses structured queries:\n\n```\nfield,operator,value\n```\n\n| Field | Meaning |\n|---|---|\n| `any` | All fields (recommended for starters) |\n| `title` | Title only |\n| `creator` | Author / creator |\n| `sub` | Subject headings / topics |\n\n| Operator | Meaning |\n|---|---|\n| `contains` | Term is present |\n| `exact` | Exact match |\n| `begins_with` | Starts with |\n\n**Examples:**\n\n```\nany,contains,Volksschule Zürich\ntitle,contains,Pädagogik\ncreator,exact,Einstein Albert\nsub,contains,Bildungsforschung\ntitle,contains,Schule;sub,contains,Geschichte\n```\n\n### Available Archives\n\n| Identifier | Description |\n|---|---|\n| `ETH_Hochschularchiv` | Institutional memory of ETH Zurich |\n| `ETH_MaxFrischArchiv` | Estate of Swiss author Max Frisch |\n| `ETH_ThomasMannArchiv` | Letters and documents of Thomas Mann |\n| `ETH_GraphischeSammlung` | Prints, drawings, graphic works |\n| `ETH_Bildarchiv` | Science/technology history, Swissair (E-Pics) |\n\n### Example Use Cases\n\n| Query | Tool |\n|---|---|\n| *\"Find books about Zurich school history\"* | `eth_search_education` |\n| *\"What's in the Max Frisch archive?\"* | `eth_search_archive` |\n| *\"Find historical maps of Switzerland\"* | `eth_search_by_type` |\n| *\"Get full metadata for resource ID 991170525863705501\"* | `eth_get_resource` |\n| *\"Which archives does the ETH Library hold?\"* | `eth_library_info` |\n\n---\n\n## Project Structure\n\n```\neth-library-mcp/\n├── src/\n│   └── eth_library_mcp/\n│       ├── __init__.py        # Package init, version\n│       └── server.py          # FastMCP server, all tools\n├── tests/\n│   └── test_server.py         # Unit tests\n├── CHANGELOG.md\n├── CONTRIBUTING.md             # Contribution guide (English)\n├── CONTRIBUTING.de.md          # Contribution guide (German)\n├── SECURITY.md                 # Security posture (English)\n├── SECURITY.de.md              # Security posture (German)\n├── LICENSE\n├── README.md                  # This file (English)\n├── README.de.md               # German version\n├── claude_desktop_config.json # Example Claude Desktop configuration\n└── pyproject.toml             # Build configuration\n```\n\n---\n\n## MCP Protocol Version\n\nThis server speaks **two protocol eras** over the same endpoint. The client's\nfirst request on a connection decides which one applies; a later claim from the\nother era is refused.\n\n| Era | Revision | Who reaches it |\n|---|---|---|\n| `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. |\n| Per-request envelope | **`2026-07-28`** | A request carrying the `2026-07-28` `_meta` envelope opens a modern connection. |\n\nBoth revisions are pinned in\n[`tests/test_protocol_version.py`](tests/test_protocol_version.py) and asserted\nagainst the installed SDK, so a Dependabot bump of `mcp` cannot move either one\nsilently. The handshake ceiling is measured against a live `initialize` through\nthe assembled ASGI stack, not read off a constant name.\n\nNote that the SDK's `LATEST_PROTOCOL_VERSION` is an alias for the **modern**\nera, not for the handshake era — pinning against it alone would leave the era\nthat current clients actually negotiate free to drift.\n\n**Update policy.** When the gate fails, do not edit the constant blindly: read\nthe spec changelog between the two revisions, verify the server still behaves,\nthen move the constant, this section, `README.de.md` and\n[`CHANGELOG.md`](CHANGELOG.md) together.\n\n---\n\n## Testing\n\n```bash\n# Unit tests (no API key required)\nPYTHONPATH=src pytest tests/ -m \"not live\"\n\n# Integration tests (API key required)\n# Live checks against the gateway — these need NO API key\nPYTHONPATH=src pytest tests/ -m \"live\"\n\n# Re-record the route census (writes tests/fixtures/PROVENANCE.md)\npython scripts/record_fixtures.py\n```\n\nUntil 2026-08-08 this repository had **no live tests at all** — `pytest -m live`\ncollected zero. Nothing in it had ever been held against the source.\n\nThe Discovery payloads still cannot be recorded: the API requires a key, and\n`tests/fixtures/PROVENANCE.md` lists them explicitly as **NOT RECORDED** rather\nthan giving them a date they never had. What *is* recordable is the contract the\nsource gives up without a key — **which routes the gateway serves** — and that is\nexactly what the finding hangs on. The two `control_*` entries are part of the\nmeasurement, not decoration: without them the recording only proves that someone\ngot a 404; with them it proves what the gateway distinguishes.\n\nThe two live tests need no key and say something anyway: they report if the\nPersons API comes back (then the tool should return) or if Discovery loses its\nroute (then five tools are affected).\n\n\n---\n\n## Safety & Limits\n\n- **Read-only:** All tools perform HTTP GET requests only — no data is written, modified, or deleted.\n- **No personal data:** The APIs return bibliographic metadata (titles, authors, subjects, identifiers). No personally identifiable information (PII) is processed or stored by this server.\n- **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.\n- **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.\n- **Data freshness:** Results reflect the ETH Library catalogue at query time. No caching is performed by this server.\n- **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.\n- **No guarantees:** This is a community project, not affiliated with the ETH Library or ETH Zurich. Availability depends on upstream APIs.\n\n---\n\n## Contributing\n\nContributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) ([Deutsch](CONTRIBUTING.de.md)) for guidelines.\n\n---\n\n## Security\n\nRead-only, no PII, a single upstream API key, and a fixed egress allow-list of\nETH Library endpoints. See [SECURITY.md](SECURITY.md) ([Deutsch](SECURITY.de.md))\nfor the full security posture and accepted-risk decisions.\n\n---\n\n## Changelog\n\nSee [CHANGELOG.md](CHANGELOG.md)\n\n---\n\n## License\n\n- **Server code:** MIT License — see [LICENSE](LICENSE)\n- **Bibliographic metadata:** Public Domain (no restrictions)\n- **API documentation:** [developer.library.ethz.ch](https://developer.library.ethz.ch)\n\n---\n\n## Author\n\n**Hayal Oezkan** · [github.com/malkreide](https://github.com/malkreide)\n\n---\n\n*Powered by [Model Context Protocol](https://modelcontextprotocol.io/) • 1 API • 6 Tools • 2 Resources • 2 Prompts*\n\n<!-- mcp-name: io.github.malkreide/eth-library-mcp -->\n\n<!-- BEGIN GENERATED: install -->\n## Installation\n\nRun 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`):\n\n```json\n{\n  \"mcpServers\": {\n    \"eth-library-mcp\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"eth-library-mcp\"\n      ]\n    }\n  }\n}\n```\n<!-- END GENERATED: install -->\n",
  "bytes": 14391,
  "sha": "a49bc4cadfff53bd16ab1297244a6de326749adb7b4b07dbb7be4165982c5164",
  "repo_slug": "malkreide/eth-library-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_malkreide_eth_library_mcp_4046de77/readme"
}