snac-archives-mcp
Builds ArchiveGrid search and record links for OCLC's ArchiveGrid service, allowing users to open fielded searches or collection records for archival materials that SNAC may not find; it does not automate ArchiveGrid access due to OCLC's terms of use.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@snac-archives-mcp which archive holds the papers of Jane Addams?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Tool | Purpose |
| 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). |
| One collection in full: the whole abstract, extent, repository, links, and the names SNAC connects to it. |
| What SNAC links to one repository, filtered by title and paged. |
Finding people, families and organisations
Tool | Purpose |
| Find SNAC name records by name, optionally by kind: person, family, or corporate body (churches, businesses, societies, offices). |
| One name record: headings, dates, places, biographical note and identifier links (VIAF, Library of Congress and others). With |
| 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 |
| Build an ArchiveGrid search, in its fielded syntax, for you to open; or a record link, given an OCLC number. Makes no request. |
| 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-mcpFrom 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 clientEither 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-mcpConfiguration
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 |
| The SNAC REST endpoint. Default |
| Response cache directory. Default |
| HTTP timeout in seconds. Default 60. Holdings lists get 120. |
| 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_kindisfinding_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_collectionsneeds 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. Usesearch_names, or an ArchiveGrid link withplace.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_ofgroups 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,
creatorOfmeans these are the name's own papers;referencedInmeans the name is an index term on the collection, not that any document concerns the person.maybe_same_countabove 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.
locationis where the repository is;placeis 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_URLmust 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 APIThe 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 toolsarchivegrid_search_linkARead-only
Build an ArchiveGrid search address for the user to open. Makes no network call.
ArchiveGrid often finds what SNAC cannot: collections known only by place or subject, and HTML or PDF finding aids. OCLC forbids automated access, so give the link to the user; never fetch it. Fielded indexes cover catalogue records and EAD only; HTML and PDF finding aids match keywords only. Over 90% of hits are collection-level WorldCat records, and microfilm held by many libraries (county or church records) is usually missing.
Inputs: event, place, title, topic, +10 more.
cache_statusARead-only
Report this session's SNAC calls and cache use. Makes no network call.
Inputs: no named parameters.
collections_in_commonARead-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_collectionARead-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_nameARead-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_holdingsARead-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_collectionsARead-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_namesARead-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
Scored across 8 tools
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.
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.
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.
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
Related MCP Connectors
Read-only OpenHeritage search for genealogy and cultural heritage records.
Search LOC digital collections, Chronicling America newspapers (full OCR), and LC Subject Headings.
Machine-readable entity discovery with provenance, trust and verified source evidence.
Search the Wayback Machine and IA library (40M+ items), fetch snapshots, item metadata, and text.
Related MCP Servers
- AlicenseAqualityAmaintenanceEnables 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.227Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables querying genealogical records, archive statistics, historical weather, and full-text transcriptions from Open Archives via natural language.12 npm4-
- AlicenseAqualityCmaintenanceEnables searching and retrieving historical Swedish portraits, biographies, and printed source references from Svenskt Porträttarkiv, including direct image links and genealogical citations.3MIT
- AlicenseAqualityBmaintenanceEnables 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.1856 PyPIMIT