SNAC Archives README

snac-archives-mcp

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

Finding people, families and organisations

Where SNAC stops

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.

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.

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.