oai-pmh-mcp

Nothing to configure — the repository address is passed at tool-call time, so a single installation handles any number of repositories.

A universal MCP server for the OAI-PMH protocol (Open Archives Initiative – Protocol for Metadata Harvesting).

It lets any MCP client (Claude, ChatGPT, Cursor…) query any public OAI-PMH repository — digital libraries built on dLibra (e.g. the Wielkopolska Digital Library), as well as DSpace, EPrints, PubMed Central and others — with no per-host configuration. The repository address (base_url) is supplied on every call.

Features

A faithful wrapper around the six OAI-PMH verbs plus a convenient layer for bulk harvesting:

Tool	Role
identify	repository identity (name, protocol version, granularity, deleted-record policy)
list_metadata_formats	available metadata formats (oai_dc, mods, marc…)
list_sets	collections / sets
list_identifiers	record headers only (cheap overview)
list_records	a page of full records + pagination token
get_record	a single record by identifier
harvest_records	auto-pagination: fetches multiple pages up to a limit, resumable

Output in three formats (format): text (default, token-efficient), json (machine-readable), xml (raw original).

Installation

uvx oai-pmh-mcp        # run without installing (stdio)
# or
uv tool install oai-pmh-mcp

MCP client configuration

Claude Code

claude mcp add oai-pmh -- uvx oai-pmh-mcp

mcp.json (Cursor / others)

{
  "mcpServers": {
    "oai-pmh": { "command": "uvx", "args": ["oai-pmh-mcp"] }
  }
}

Transport

Defaults to stdio. Remote mode uses streamable-HTTP:

oai-pmh-mcp --transport http --host 0.0.0.0 --port 8000

Example

"Check what collections https://www.wbc.poznan.pl/dlibra/oai-pmh-repository.xml has and show the 5 most recent records."

The model will call identify → list_sets → list_records and assemble the answer.

One prompt, pointed at the Wielkopolska Digital Library. identify confirms the endpoint — OAI-PMH 2.0, records back to 2003-12-01, deletedRecord: persistent. list_sets returns all 116 sets and finds the interesting ones under rootCollection:wbc:Mirabilium. list_records then reads out Masonica (267 records): the Grand Lodge of Hamburg library, confiscated during the war and now held in Poznań — including a 1782 exposé of Masonic ritual and the by-laws of a London lodge that met in the Half-Moon Tavern on Cheapside.

Nothing about that repository is hardcoded — the same tools answer the same way for any OAI-PMH endpoint you name.

Development

uv sync
uv run pytest            # unit tests (offline, fixtures)
uv run pytest -m integration   # network tests (optional)
uv run ruff check .

Scope

OAI-PMH is a metadata protocol — the server does not fetch object content (scans, PDFs). It is read-only, without authentication, without caching.

Security

• XML parsing is hardened — the parser does not expand entities or reach out to the network/DTD (protection against XXE and "billion laughs" from untrusted repositories).
• harvest_records has hard limits (max records, max pages, abort on lack of progress) — a malicious server cannot trap the client in a loop.
• SSRF by design: the server fetches any base_url supplied by the client (that is the point). Only the http/https schemes are allowed. If you deploy the remote (HTTP) variant on a network with internal resources, run it in an environment with restricted outbound networking — the model could point at an internal address (e.g. a cloud metadata endpoint).

License

MIT