z3950-mcp

Install YAZ first — brew install yaz (macOS) or apt-get install yaz (Debian/Ubuntu). Z39.50 is spoken by yaz-client, a system binary no installer can ship; the buttons install the server around it. Without YAZ the server still starts and every search returns an explicit yaz-client not found error.

A desktop app does not inherit your shell's PATH, so the server also looks in Homebrew's usual locations on its own. If YAZ lives somewhere unusual, point YAZ_CLIENT at the binary (the Claude Desktop installer offers a field for it).

An MCP server that lets an AI assistant search library catalogs over Z39.50 and get back structured MARC 21 records.

It talks to catalogs through YAZ (yaz-client) and parses the returned records with pymarc, so you get clean, standards-based bibliographic data — not scraped HTML.

Why

Most Polish (and international) library OPACs — Prolib/Integro, Virtua, Aleph, Alma, Koha — expose a Z39.50 server, the decades-old library-standard search protocol. It returns MARC 21, which is far more reliable to consume than scraping a web catalog. This server puts that behind two simple MCP tools.

Requirements

• Python ≥ 3.10
• The YAZ toolkit (yaz-client):
  • macOS: brew install yaz
  • Debian/Ubuntu: apt-get install yaz

The binary is looked up on PATH first, then in /opt/homebrew/bin and /usr/local/bin. Those two exist because a desktop MCP host — Claude Desktop, Cursor — is launched from the GUI and inherits launchd's PATH (/usr/bin:/bin:/usr/sbin:/sbin), which contains no Homebrew: without the fallback, a correctly installed YAZ would still look missing.

Set YAZ_CLIENT to an absolute path to override the search entirely. A value that is not executable is an error rather than a reason to keep looking — otherwise a typo would surface much later as a confusing "not found".

Install

git clone https://github.com/mpasternak/z3950-mcp
cd z3950-mcp
uv sync

Tools

list_targets()

Lists the preconfigured catalogs — see Public Z39.50 resources below. Each entry's key can be passed to search.

search(target, query, by="any", start=1, count=5, include_raw_marc=false)

Searches a catalog and returns parsed MARC records.

• target — a registry key above, or an ad-hoc host:port/database string.
• by — index to search: any, title, author, subject, isbn, issn, publisher, year, lccn, id, or pqf to pass query through as a raw PQF query.
• count — how many records to return (max 50). Use count=1 with a narrow query (e.g. by ISBN) to fetch a single full record.
• include_raw_marc — also include the full MARC record as text.

Example result for search("bn", "Pan Tadeusz", by="title", count=1):

{
  "target": "bn-nl.alma.exlibrisgroup.com:1921/48OMNIS_NLOP",
  "query": "@attr 1=4 \"Pan Tadeusz\"",
  "hits": 1406,
  "returned": 1,
  "records": [
    {
      "control_number": "991000041299705066",
      "title": "Pan Tadeusz czyli Ostatni zajazd na Litwie : historia szlachecka...",
      "author": "Mickiewicz, Adam (1798-1855)",
      "year": "1994",
      "isbn": ["8370010938"],
      "publisher": "\"Alfa-Wero\"",
      "language": "pol",
      "subjects": ["Poezja polska -- 19 w."]
    }
  ]
}

Public Z39.50 resources

Catalogs below were verified reachable (2026-07) — they return live MARC 21. Ones with a key are built in (search("bn", …)); the rest you pass as an ad-hoc host:port/database.

Polish

The National Library has the broadest Polish holdings. Most other Polish libraries expose Z39.50 only through the KaRo federation and don't publish their host/port openly — to find more:

• KaRo (Katalog Rozproszony Bibliotek Polskich) — https://karo.umk.pl, a YAZ broker over ~120 Polish library targets.
• IRSpy target registry — https://irspy.indexdata.com.
• NUKAT (union catalog) provides its Z39.50 parameters on request only.

English / international

The Library of Congress also serves a MARC-8 database at lx2.loc.gov:210/LCDB_MARC8 (pymarc transcodes it to Unicode). The Index Data server is a tiny demo database, handy for testing this MCP without hitting a real library.

Examples

search("demo", "computer")                           # tiny test database — smoke test
search("bn", "Lem Solaris")                          # Polish National Library
search("loc", "9780262033848", by="isbn")            # Library of Congress, by ISBN
search("nkc", "Kafka", by="author", count=3)         # Czech National Library
search("aleph.nkp.cz:9991/NKC", "Švejk")             # same, as an ad-hoc target

Use with Claude Code / Claude Desktop

Claude Code (CLI)

Register the server with claude mcp add. The -s user scope makes it available in all your projects; drop it for the current project only.

Straight from the public repo (no clone needed):

claude mcp add z3950 -s user -- uvx --from git+https://github.com/mpasternak/z3950-mcp z3950-mcp

From PyPI once released:

claude mcp add z3950 -s user -- uvx z3950-mcp

From a local checkout (for development):

claude mcp add z3950 -s user -- uv run --directory /path/to/z3950-mcp z3950-mcp

Remove it again with claude mcp remove z3950 -s user.

Claude Desktop (JSON config)

Add to claude_desktop_config.json (stdio transport):

{
  "mcpServers": {
    "z3950": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/mpasternak/z3950-mcp", "z3950-mcp"]
    }
  }
}

Adding catalogs

Append a Target(...) to _TARGETS in src/z3950_mcp/targets.py, or just pass an ad-hoc host:port/database to search. Finding a library's Z39.50 coordinates: the IRSpy registry lists many; some (e.g. NUKAT) provide them on request.

Development

uv run pytest              # unit tests (offline)
uv run pytest -m integration   # live tests against BN + LoC (network + yaz)
uv run ruff check .

Releasing

Releases publish to PyPI via Trusted Publishing (OIDC — no API tokens). Publishing a GitHub Release (or pushing a v* tag) triggers .github/workflows/publish.yml, which builds and uploads from the pypi environment. The PyPI project must have a matching trusted publisher (repo mpasternak/z3950-mcp, workflow publish.yml, environment pypi).

License

MIT — see LICENSE.