Matricula Church Books

matricula-mcp

An MCP server for Matricula Online (data.matricula-online.eu), the church-book portal that ICARUS, the International Centre for Archival Research, runs for dioceses and archives in Germany, Austria, Poland, Slovenia, Serbia, Italy, Switzerland, Luxembourg and Bosnia and Herzegovina. Matricula publishes their parish registers (baptisms, marriages and burials, and the indexes, family books and parish censuses that go with them), scanned page by page: about 13,400 parishes by its own count in October 2026.

The server walks Matricula's own hierarchy. It lists the countries and their *sections* (each a diocese, an archive or a private collection), a section's parishes with their coordinates, a parish's registers with their signatures, types and dates, and a register's pages, each with its label and the link that opens it in Matricula's own viewer. It also runs Matricula's place search, which finds the parish a village belonged to.

It works the way a careful genealogist does. The register page is the evidence. A register's type and dates, a page label and a search snippet are finding aids that say which page to open. Every result carries a citation in the order Matricula itself gives for finding a page again: diocese or archive, parish, register signature, page.

Page images are read in Matricula's viewer, not fetched by this server. Matricula's image host refuses scripted requests, and this server does not pretend to be a browser to get past it. The code that would save one page image is here, documented and tested, but switched off: it is for the day ICARUS grants access to an identified client. See Page images.

Nothing here writes to Matricula, and nothing here keeps a family tree.

This is an independent project. It is not affiliated with, endorsed by, or supported by ICARUS or any of the archives and dioceses whose registers Matricula publishes.

Tools

The server publishes seven tools. All but matricula_page_image are read-only; that one creates a new file only when image access is on, and never overwrites one.

Finding

Reading

Everything is addressed by its path on Matricula below the language prefix, which the tools call a key: deutschland/passau is a section, oesterreich/salzburg/krimml a parish, oesterreich/salzburg/krimml/TFBI a register. Every tool also takes a Matricula address in any of its interface languages, and a register's tools take a page's viewer address (?pg=N).

Setup

You need Python 3.11 or later and uv. There is no key to request.

Without cloning. uvx fetches it from PyPI and runs it in one step:

uvx matricula-mcp

From a clone, which is what you want if you will change it:

git clone https://github.com/ianderso/matricula-mcp

cd matricula-mcp uv sync uv run matricula-mcp # stdio server, usually launched by the client

Either way the server speaks MCP over stdio, so you will normally let an MCP client start it rather than run it by hand.

Claude Desktop

{

"mcpServers": { "matricula": { "command": "uvx", "args": ["matricula-mcp"], "env": { "MATRICULA_CONTACT": "you@example.org" } } } }

A desktop app does not always inherit your shell's PATH. If the server fails to start because uvx cannot be found, give the full path that which uvx prints as the command.

Claude Code

claude mcp add matricula -e MATRICULA_CONTACT=you@example.org -- uvx matricula-mcp

Configuration

Nothing is required. A .env file in the directory the server starts in supplies anything the environment does not; only that directory is read.

An unusable value is reported on the first tool call as a not_configured result naming the variable.

Page images

Matricula's viewer loads each page from img.data.matricula-online.eu. That host answered 403 to a plain scripted request when this project surveyed it (with Vary: Origin), and the viewer attaches a per-session token, computed in the browser, to every image request. That is Matricula's access control, and this server treats it as one. It does not imitate a browser, send an Origin or Referer header, carry a session cookie, or reproduce the viewer's token, and it never probes the host to find out what would get through. A test fails if anything resembling a browser disguise appears in the source.

So, by default, matricula_page_image fetches nothing. It answers images_not_enabled with the page's viewer link, its label and its citation, and the person reads the page in Matricula's viewer.

The code that would save a page is written and tested against a mocked host, for the day ICARUS grants access to an identified client. If you obtain that permission (by agreement with ICARUS, for your own client), set MATRICULA_CONTACT to the address ICARUS knows you by and MATRICULA_IMAGE_ACCESS=granted. The tool then fetches one page at a time from the image host, paced like every other request, with this server's own User-Agent (matricula-mcp/ (+https://github.com/ianderso/matricula-mcp; )) and nothing else. If the host still refuses, the tool says so (image_refused) and writes nothing. Should ICARUS specify a different route (an API, a key, another host), the client is to change in a release to use exactly that route; no setting here invents one.

A saved page is a new .jpg, never a hidden file or one under ~/Library (unless MATRICULA_DOWNLOAD_DIR is set there), and comes with its citation and its licence, CC BY-NC-ND 2.0.

Being a good guest

Matricula is one service, run by an association of archives. The client sends one request at a time, at least two seconds apart, and a place search at least ten seconds after the last, because a search reads every parish description in the portal. Country and section lists and parish lists are cached for 28 days, parish and register pages for 7, searches for a day. Two identical calls in flight share one request. A 429, a 5xx or a dropped connection gets one retry, honouring Retry-After; a refusal is not retried. The User-Agent names the package, its version, this repository and, when set, your contact. No cookies are kept.

What Matricula's terms say

The terms of use (German; checked 2026-10-11) cover the images and descriptive metadata on data.matricula-online.eu:

• Every church-book image is licensed CC BY-NC-ND 2.0: "Eine kommerzielle Weiterverwertung der Bilder ist demnach nicht gestattet" (commercial reuse is not permitted). No altered versions, either.
• Data from the registers may be used only as each country's civil-status and data-protection law allows; registers holding protected data are not shown. In Austria, baptism books are closed for 100 years, and marriage and death books are shown up to 1938.
• Anyone who publishes, in print or online, using even a little of the data or images undertakes to inform the archive or diocese concerned; for online publications a link is enough, and substantial print use calls for a copy.
• They say nothing about automated access.

matricula_parishes passes on each section's own note, which often names the archive and how to reach it: the place to send that notice.

robots.txt, as a fact

Matricula's robots.txt (served from cdn-static.matricula-online.eu, read 2026-10-11) names several crawlers, ClaudeBot, GPTBot and CCBot among them, with Disallow: /, and asks every other agent to keep away from four kinds of address: the viewer's page parameter (/*?pg=), the search (/*/suchen), the map features (/*/landkarte-features) and accounts. This server is not a crawler: it reads the pages a researcher asks for, one at a time, and caches them. It reads the search (matricula_search) and one map features file per section (for matricula_parishes' coordinates); it builds ?pg= links for a person to open and never requests them; it never touches accounts. Whether that suits your use is yours to judge.

How to read what comes back

• Cite the hierarchy, keep the link as a locator. Matricula advises finding a page again through diocese or archive, parish, register signature and page, and does not promise that its links last. Each result's citation gives them in that order, with cite_as as one sentence.
• `page` is the image's position in the register, counted from 1, which is what the viewer's ?pg= takes. The label (02-Taufe_0001, 001-03_0004-r) is the archive's name for the scan: a section and number, or a folio and side. Cite both.
• `type` is the archive's word; `kind` is this server's reading of it. Index - Taufen and Passau's Register Taufen are indexes (index: true); Baden-Württemberg's Taufregister is the register itself.
• A register with `hosted_elsewhere` is listed in Matricula but shown on the archive's own site (the Landesarchiv Baden-Württemberg's section links to its permalinks). Its images are not in Matricula's viewer.
• A gap is not an absence. A register missing from Matricula may be closed by law, unscanned at the diocese or ar