z3950-mcp 0.1.0

MCP server for searching library catalogs over Z39.50 and retrieving MARC 21 records.

z3950-mcp

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 on your PATH (yaz-client):
  • macOS: brew install yaz
  • Debian/Ubuntu: apt-get install yaz

Install

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

Tools

list_targets()

Lists the preconfigured catalogs. Each entry's key can be passed to search.

key	library	connection
bn	Biblioteka Narodowa (Poland)	bn-nl.alma.exlibrisgroup.com:1921/48OMNIS_NLOP
loc	Library of Congress (Voyager)	z3950.loc.gov:7090/VOYAGER
loc-lcdb	Library of Congress (LCDB)	lx2.loc.gov:210/LCDB
nkc	Národní knihovna ČR	aleph.nkp.cz:9991/NKC

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

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.