Matricula Church Books

What Matricula Church Books MCP server does

The Matricula Church Books MCP server connects an MCP client to Matricula Online, a church-book portal operated by ICARUS for participating dioceses and archives. It exposes the portal’s catalogue hierarchy without writing changes to Matricula or maintaining a family tree.

Research begins with countries and sections, where sections represent dioceses, archives, or private collections. From there, the server can identify parishes, inspect a parish’s registers, and enumerate the pages belonging to a selected register. Results include the identifying information needed to return to a source in Matricula’s own viewer, including citations built from the archive or diocese, parish, register signature, and page.

How it works

The Matricula Church Books MCP server communicates over stdio, so an MCP client normally starts it as a subprocess. Its tools address Matricula locations using path-like keys, such as a section, parish, or register path, and also accept Matricula addresses in supported interface languages. Register operations can use a viewer page address with a page query parameter.

Catalogue requests are paced to avoid sending rapid successive requests to Matricula. Responses are cached by request type: country, section, and parish lists for longer periods than searches, while place searches have their own interval because they inspect parish descriptions. A session status tool reports request pacing, cache activity, and whether image access is enabled without making a network request.

Setup and configuration

Python 3.11 or newer and uv are required. The package can be launched without cloning the repository using uvx matricula-mcp; a cloned checkout can use uv sync followed by uv run matricula-mcp.

No API key is required for catalogue reading. Optional environment variables control the cache directory, HTTP timeout, request intervals, contact information, and download location. MATRICULA_CONTACT adds an identifying email address or URL to requests. MATRICULA_DOWNLOAD_DIR selects an existing folder for permitted image downloads.

Tools and capabilities

The Matricula Church Books MCP server provides these capabilities:

• List countries, sections, and parish counts.
• Find parishes within a section by name, including coordinates and section notes.
• Search for places mentioned in parish names or descriptions, optionally restricted by section or year range.
• List a parish’s registers with signatures, register types, kinds, dates, notes, holding institutions, and keys.
• Retrieve a register’s description, citation, pages, labels, positions, and viewer links, with paging and label filtering.
• Report session cache and request status.

Limitations and notes

The page-image tool is disabled unless ICARUS has granted access to the client. When disabled, it returns an images_not_enabled result containing the viewer link, label, and citation rather than fetching an image. If access is granted and the required settings are supplied, it can save one page as a new JPEG; it does not overwrite existing files.

The normal workflow is therefore to use the server to locate and identify a page, then read the scan in Matricula’s viewer. The server does not bypass the image host’s access controls, imitate a browser, or retrieve images by disguising requests. If an authorized image request is refused, no file is written.

The project is independent of ICARUS and the archives and dioceses represented on Matricula. Register metadata, snippets, and page labels are finding aids; the page in the portal remains the evidence to inspect.