Skip to main content
Glama
snac-archives-mcp

snac-archives-mcp

by ianderso

snac-archives-mcp

CI PyPI

An MCP server for finding which archive holds the papers: a family's letters, a church's registers, a store's ledgers, a county office's loose papers. Most of that material has never been digitised. It exists online only as a catalogue record or a finding aid in some library, and the hard part of the research is knowing which one.

The server searches the SNAC Cooperative's index of people, families and organisations and the archival collections that hold their papers, across thousands of repositories. The data is CC0, and the API needs no key and no account. It also builds ArchiveGrid searches for you to open, because ArchiveGrid often finds what SNAC cannot, and OCLC does not permit automated access to it.

It works the way a careful genealogist does. Everything it returns is a finding aid: evidence of where to look and roughly what is there, never of what a document says. The tools say so, and they point you at the holding repository's own finding aid, which is the description to cite.

Nothing here writes anywhere, and nothing here keeps a family tree. The server finds collections; what you conclude from the papers belongs in your genealogy software, or in a family-tree MCP server running alongside this one. It sits well beside nara-catalog-mcp (federal records) and familysearch-mcp (indexed records and images).

This is an independent project. It is not affiliated with, endorsed by, or supported by the SNAC Cooperative, the University of Virginia, or OCLC.

Tools

The server publishes eight tools, all read-only and annotated so for the client. Two make no network call at all.

Finding collections

Tool

Purpose

search_collections

Find collections by words in their title. Each hit names its holding repository with a postal address, its OCLC number and its link, and flags the likely duplicates (the same papers catalogued two or three times).

get_collection

One collection in full: the whole abstract, extent, repository, links, and the names SNAC connects to it.

repository_holdings

What SNAC links to one repository, filtered by title and paged.

Finding people, families and organisations

Tool

Purpose

search_names

Find SNAC name records by name, optionally by kind: person, family, or corporate body (churches, businesses, societies, offices).

get_name

One name record: headings, dates, places, biographical note and identifier links (VIAF, Library of Congress and others). With detail="full", every collection linked to it, with its role, and the related names.

collections_in_common

Collections linked to both of two names: where to look for letters between intermarried families or an ancestor's associates.

Where SNAC stops

Tool

Purpose

archivegrid_search_link

Build an ArchiveGrid search, in its fielded syntax, for you to open; or a record link, given an OCLC number. Makes no request.

cache_status

This session's live calls and cache hits. Makes no request.

Related MCP server: Open Archives MCP Server

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 snac-archives-mcp

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

git clone https://github.com/ianderso/snac-archives-mcp
cd snac-archives-mcp
uv sync
uv run snac-archives-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": {
    "snac": {
      "command": "uvx",
      "args": ["snac-archives-mcp"]
    }
  }
}

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 snac -- uvx snac-archives-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.

Variable

Meaning

SNAC_API_URL

The SNAC REST endpoint. Default https://api.snaccooperative.org/. Must be https; its host is the only one the server will contact.

SNAC_CACHE_DIR

Response cache directory. Default ~/.cache/snac-archives-mcp.

SNAC_TIMEOUT

HTTP timeout in seconds. Default 60. Holdings lists get 120.

SNAC_CONTACT

An email address or URL added to the User-Agent, so the SNAC team can reach you if your use causes trouble. Optional, and courteous.

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

Being a good guest

SNAC is a free service run by a small cooperative, and it publishes no rate limit. The server sends one request at a time, at least a second apart; two identical calls in flight share one request; and every answer is cached on disk for 30 days (a collection record for good). A 429 or a 5xx is retried three times with back-off, then reported as rate_limited or upstream_error, which is never the same as "nothing found". Pass refresh=true to ask again, and refresh a cached empty result before concluding anything is absent.

How to read what comes back

  • A finding aid is not the record. A collection description says the papers exist and roughly what is in them. Do not attach a citation to a fact on its strength; record a research task (request copies, plan a visit) instead.

  • Cite the repository's own finding aid, by the repository and its collection number, for example "Wilder and Anderson Family Papers #01255, Southern Historical Collection, Wilson Library, UNC-Chapel Hill". Not SNAC, and not ArchiveGrid: they are indexes to it. When link_kind is finding_aid, the link goes there; otherwise look the collection up in the repository's own catalogue.

  • Record the identifiers. The OCLC number ties a collection together across WorldCat, ArchiveGrid and SNAC; the SNAC ARK (ark:/99166/...) is the stable id of a name record. Record the repository's collection number too: WorldCat merges records, and a number can come to redirect to another.

  • Description depth varies enormously, from a one-line catalogue record ("Papers, 1881-1958", 4 boxes) to a folder-level container list. A terse description does not mean a person is absent from the papers.

  • Title search is title search. search_collections needs every word in the collection's title. "Davenport family papers" finds ten collections; "Davenport family papers Lincoln County" finds none, because the county is only in the abstract. Use search_names, or an ArchiveGrid link with place.

  • Duplicates are normal. One collection often appears as a WorldCat record and as one or two harvested finding aids, sometimes under different forms of the repository's name. possible_duplicate_of groups them by title words and years; it is a hint, not a merge.

  • A name record is not an identification. SNAC holds hundreds of records headed "Anderson family." with nothing to tell them apart but the collections they link to. In a name's collections, creatorOf means these are the name's own papers; referencedIn means the name is an index term on the collection, not that any document concerns the person. maybe_same_count above 0 means SNAC suspects a conflation.

  • The papers of slaveholding families are a primary route to enslaved ancestors. Many descriptions name enslaved people only as a category. Search the papers of the family that held them, not only the ancestor's name.

  • The catalogue ages. SNAC's collection index was largely built from 2010s extracts. Collections get reprocessed, renumbered and transferred, and survey "repositories" such as a state historical documents inventory record what a town clerk or church held when surveyed decades ago. Confirm the current call number before writing to a repository.

  • ArchiveGrid's indexes have edges. location is where the repository is; place is a place the papers are about. Its name, place and subject indexes cover catalogue records and EAD finding aids only; HTML and PDF finding aids match keywords alone. It leaves out records held by more than one library, so microfilm of county or church records is usually missing: use WorldCat or the FamilySearch Catalog for that.

Deliberately not here

  • Writing to SNAC. Its edit commands need an account and an API key. The client refuses to send any command but its six read ones, so no argument can make it edit anything.

  • Fetching ArchiveGrid. OCLC's terms of use forbid robots and automated copying, and the site blocks automated clients. The server builds addresses; a person opens them.

  • Fetching finding aids from repositories' own sites. That would widen the server from one API to thousands of hosts, with a parser for each and a much larger surface for injected text. It may come later, behind an option.

Security

  • One host. A request hook refuses any request not for the configured API host, so a value a model passes in cannot make the server fetch another site. SNAC_API_URL must be https.

  • Identifiers are validated (numeric ids as ASCII digits, ARKs against SNAC's pattern) before they reach a request.

  • Catalogue text is untrusted. Abstracts and biographical notes are written by cataloguers and contributors and reach the model verbatim. The server's instructions tell the model to treat that text as material to weigh, never as instructions; the model still decides, so review what it proposes to do.

To report a vulnerability, see SECURITY.md.

Development

uv sync --extra dev
uv run pytest                      # mocked with respx; never touches SNAC
uv run ruff check .
uv run ruff format --check .
uv run python -m tests.live_check  # eight paced calls to the live API

The live check asks SNAC what the recorded fixtures cannot: whether its answers still have the shape the server reads. See CONTRIBUTING.md for how the suite is organised, docs/API-NOTES.md for what was observed of the API and when, and docs/DESIGN.md for why the server is shaped this way.

Credits

The data is the SNAC Cooperative's, released under CC0, with collection records contributed by its member institutions and drawn from WorldCat and finding aids. ArchiveGrid is a project of OCLC Research.

License

MIT.

Available Tools

8 tools
cache_statusA
Read-only

Report this session's SNAC calls and cache use. Makes no network call.

Inputs: no named parameters.

collections_in_commonA
Read-only

List the collections linked to both of two names.

Useful for intermarried families and the associates around an ancestor: papers that mention both are where to look for letters between them. Two names on one collection do not show the two people knew each other.

Inputs: first (required), second (required), refresh.

get_collectionA
Read-only

Read one collection description in full, with the names SNAC links to it.

Depth varies: a one-line MARC record with no box or folder list is normal, and a terse description does not mean a person is absent from the papers. Follow link (when link_kind is finding_aid) or the repository's own catalogue to the finding aid; that is the description to cite, by its collection number. Record oclc_number. "[microform]" in a title means a copy; the original is elsewhere.

Inputs: resource_id (required), refresh.

get_nameA
Read-only

Read one SNAC name record: who or what it is, and the collections linked to it.

In collections, role creatorOf means these are the name's own papers; referencedIn means the name is an index term on the collection, not proof the person appears in any document. The biography is copied from a finding aid: secondary information to follow up, not to cite for a fact. maybe_same_count above 0 means SNAC suspects this record and another describe one entity. Record the ark, not the numeric id.

Inputs: name_id (required), detail, refresh.

repository_holdingsA
Read-only

List the collections SNAC links to one repository, filtered by title.

The first call for a large repository is slow (10 to 20 seconds; it is SNAC building a list of thousands) and is then cached. The list is SNAC's link table, not the repository's catalogue: it includes printed and microform items and misses recent accessions. Survey "repositories" such as a state historical documents inventory record what a town or church held when surveyed decades ago; the material may since have moved.

Inputs: repository (required), page, count, refresh, +1 more.

search_collectionsA
Read-only

Find archival collections by words in their title, with who holds each.

Matches the collection TITLE only, and every word must appear: a county or second surname named only in the abstract will not match, so use archivegrid_search_link or search_names for those. The same papers often appear two or three times (a WorldCat record plus harvested finding aids); possible_duplicate_of flags them. SNAC's catalogue is largely a 2010s snapshot. A hit tells you where papers are, not what they say: confirm the collection number in the repository's own catalogue, and cite its finding aid, never this result.

Inputs: title_words (required), page, count, refresh.

search_namesA
Read-only

Find SNAC name records for a person, family or organisation.

A heading such as "Anderson family." matches hundreds of unrelated families, usually one record per source collection, with no place or date to tell them apart. A SNAC record is a machine-built authority record, not an identification: narrow with get_name, reading the collections it links to and their places and dates, before treating any record as your family.

Inputs: name (required), page, count, refresh, +2 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct object or action: collection search vs. name search, collection retrieval vs. name retrieval, cross-name collection overlap, repository holdings, external link building, and cache reporting. The descriptions explicitly clarify boundaries and limitations, so an agent should not confuse them.

    Naming Consistency4/5

    All names use snake_case and are readable, with consistent search_/get_ pairs for the core lookup tools. However, several tools use noun phrases (collections_in_common, repository_holdings, cache_status) rather than the verb_noun pattern, which is a minor deviation.

    Tool Count5/5

    Eight tools are well-scoped for a read-only archival discovery server. Each tool earns its place by covering a distinct part of the SNAC research workflow without obvious redundancy.

    Completeness4/5

    The surface covers core discovery and retrieval: searching and reading collections and names, finding shared collections, browsing repository holdings, and generating an external ArchiveGrid link. Minor gaps exist, such as direct subject/place search within SNAC or citation export, but agents can work around these via the provided tools and link builder.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Enables users to search and access digital collections from the Swedish National Archives (Riksarkivet) through multiple APIs. Supports searching records by keywords, exploring collections, and downloading historical images and documents.
      2
      27
      Apache 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables searching and retrieving historical Swedish portraits, biographies, and printed source references from Svenskt Porträttarkiv, including direct image links and genealogical citations.
      3
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables users to search and browse US National Archives Catalog records, read OCR text, citizen transcriptions, tags, and comments, and download page images for genealogical or historical research. It also supports advanced filtered searches and searching within contributed document text while remaining read-only except for saving page images locally.
      18
      56 PyPI
      MIT