@cyanheads/libofcongress-mcp-server
This server has a remotely hosted endpoint. Open its connector listing for connection details, authentication requirements, and setup instructions:
Public Hosted Server: https://libofcongress.caseyjhand.com/mcp
Overview
Library of Congress digital collections, Chronicling America historic newspapers, and LC Subject Headings. Search items and newspaper pages, read full metadata and OCR text, resolve subject terms, and browse curated collections.
Tools
Tool | Description |
| Search LOC digital collections by keyword with format, date range, subject, location, contributor, and collection filters. |
| Retrieve full metadata for a specific LOC digital item — imprint, contributors, subjects, rights, formats, its digital resources, and a paged list of its pages. |
| Search historical newspaper pages in the Chronicling America corpus, with an excerpt of each page's opening OCR text. |
| Retrieve the full text and metadata of one page — a newspaper page, or a book or manuscript page from |
| Search Library of Congress Subject Headings (LCSH) by keyword. |
| List and browse LOC curated digital collections, optionally filtered by keyword. |
Resources
Resource | Description |
| LOC digital item metadata by ID — stable URI for injecting item context into agent conversations. |
All resource data is also reachable via libofcongress_get_item. Use libofcongress_search_items to discover item IDs first.
Research guide
libofcongress-guide covers identifier chains, OCR uncertainty, research coverage, and collection, newspaper, book, and manuscript workflows. It ships with plugin, npm, Docker, and MCPB installs and is also available through MCP skill discovery and resource reads.
Related MCP server: historical-investigator-mcp
Capability reference
libofcongress_search_items tool
Filters: eight material formats (
photo,map,newspaper,manuscript,audio,film,book,notated-music), inclusive year range (date_start/date_end),subject(an LCSH heading fromlibofcongress_search_subjectsor a facet term), location,contributor(a name as LOC indexes it, without dates or roles), andcollection_slug(fromlibofcongress_browse_collections, combinable withformat); up to 100 results per page — a largerlimit(up to 1000) is served as 100 witheffectiveLimitand a noticeUse
query: "*"to browse without a keyword.sortacceptsrelevance(default),date(oldest first), ordate_desc(newest first);effectiveSortechoes the order LOC applies before paginationEach result carries
dateas LOC catalogs it andis_item:truefor catalog items whoseidresolves vialibofcongress_get_item,falsefor other resources. Newspaper rows includepage_urlforlibofcongress_get_newspaper_page; retired catalog links carrylink_noticeand retain their original URL. Other non-item rows can be opened aturl.contributor_termslists the contributors LOC credits a row with, in the form thecontributorfilter acceptsinclude_facets: trueaddssubject_facets,location_facets, andcontributor_facets(LOC's top 10 terms across all matches, each with its item count); off by default since it slows every search. A zero-result notice names the subject terms, location, and contributor appliedA subject, location, or contributor value with
|inside it is rejected asinvalid_filter_value(a|at either end is dropped); a query LOC refuses as too long fails asquery_too_long
libofcongress_get_item tool
Takes a search result's
id(simple or multi-segment, e.g.sn95047246/1935-09-05/ed-1), a loc.gov item link, or anlccn.loc.govpermalink; any other URL is rejected asinvalid_item_idbefore any requestReturns the
imprint, contributors with roles andcontributor_terms(the names the searchcontributorfilter accepts), LCSHsubject_headings,subject_terms(the lowercase terms the searchsubjectfilter accepts), notes, summary, languages, locations,rights_informationas plain text, physical description, call number, former IDs, formats, andaccess_restricted; fields absent upstream are omittedresourceslists every digital resource with its page count,image,pdf,audio(MP3),video(MP4), anddownload_restricted; a recording, tape side, or film reel LOC sends with only its media file has nourland no pages.has_transcriptionmarks a resource whose document has one transcription, whichlibofcongress_get_newspaper_pagereturns for any of its pages.pageslists 50 pages at a time by default (page_offset,page_limit,page_total,next_page_offset; at most 100 per call — a largerpage_limit, up to 1000, is served as 100 witheffectivePageLimitand a notice), each with apage_urlandhas_textthat read throughlibofcongress_get_newspaper_page.include_files: trueadds each page's download URLs
libofcongress_search_newspapers tool
Filters: keyword, inclusive date range down to the day (
date_start/date_endtake an integer year or aYYYY,YYYY-MM, orYYYY-MM-DDstring), indexed state/province (full name or supported US postal code), newspaper title (the exactnewspaper_titleof a search result), andlanguage(as LOC indexes it, e.g.german; a bilingual page matches each of its languages); up to 100 results per page — a largerlimit(up to 1000) is served as 100 witheffectiveLimitand a noticesortacceptsrelevance(default),date(oldest first), ordate_desc(newest first);effectiveSortechoes the applied orderEach result carries the opening ~500 characters of the page's OCR text,
states,languages, and theurlthatlibofcongress_get_newspaper_pagetakes verbatiminclude_facets: trueaddsnewspaper_title_facets,state_facets, andlanguage_facets(LOC's top 10 values across all matches, each with LOC's page count), the values thenewspaper_title,state, andlanguagefilters accept unchanged; off by default since LOC's facet block is large. A|inside a filter value is rejected asinvalid_filter_value(one at either end is dropped); a query LOC refuses as too long fails asquery_too_longThe excerpt is the page's first lines, not the text around the match; pass the same query as
matchtolibofcongress_get_newspaper_pagefor the passages around it
libofcongress_get_newspaper_page tool
Takes the
urlfrom alibofcongress_search_newspapersresult, or apages[].page_urlfromlibofcongress_get_item(newspaper, book, and manuscript pages alike), plus Chronicling America page links; a link that names no single page, any other host, or a malformed path orspis rejected asinvalid_page_urlbefore any requestReturns the page's text as
ocr_textwithnewspaper_title,date,place_of_publication,states,edition,sequence,segment_count,item_title, anditem_id(pass it tolibofcongress_get_itemto list the item's pages).ocr_available: falsemarks an image-only page, and anoticeexplains an empty result: the text service did not answer (retry), the body could not be read as text, or the page is blankA manuscript or printed pamphlet LOC transcribed as one document (the Lincoln papers, for one) returns that whole transcription as
ocr_texton any of its pages,text_scope: "document", withtext_attributionwhen LOC names a transcriber; a page with a text service of its own istext_scope: "page". A manuscript's transcription omits the editors' notes and the wording the writer canceledmatchreturns only the passages around a term — pass the query you searched with. Space-separated words are separate terms and a double-quoted span is one phrase, matched case-insensitively.matchesholds up to 10 passages of about 300 characters either side of each occurrence,match_countcounts every occurrence, andocr_textis empty; a notice says when nothing matched or some occurrences fall outside the passages. If text retrieval fails, both match fields are absent because the result is unknown; blank and image-only pages still report zero
libofcongress_search_subjects tool
Keyword query, up to 250 results per call (default 10; a larger
limit, up to 1000, returns up to 250 with a notice); returns the authorized LCSHlabeland stable LOCuriStart at
offset: 0(default), then passnext_offsetto continue.totalcounts this page's headings; the final or past-end page omitsnext_offset. A past-end offset succeeds empty with a recovery noticeAn exact match from the first 50 results moves to the start. Subsequent offsets and changed limits preserve that ordering while the upstream results remain unchanged
Pass the label verbatim as
libofcongress_search_items'ssubjectfilter. A partial word (aerial photog) falls back to headings that begin with it
libofcongress_browse_collections tool
Optional keyword filter on collection name and description; up to 100 collections per page — a larger
limit(up to 1000) is served as a 100-collection page witheffectiveLimitand a noticeEach collection carries a
slugforlibofcongress_search_items'scollection_slug(taken from the loc.gov route, not derivable from the title);item_countis approximate and omitted when LOC doesn't provide itA keyword LOC refuses as too long fails as
query_too_long
libofcongress://item/{+item_id} resource
Returns the same record as
libofcongress_get_item, asapplication/json, with the first 50 pages and no files;next_page_offsetmarks wherelibofcongress_get_item'spage_offsetcontinuesitem_idcomes from alibofcongress_search_itemsresult'sid; anything that is not an item ID is rejected asinvalid_item_id. Multi-segment newspaper IDs keep their slashes (libofcongress://item/sn95047246/1935-09-05/ed-1)
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
Library of Congress-specific:
Request queue in front of
www.loc.gov: calls start in arrival order, at leastLOC_REQUEST_DELAY_MSapart (default 3100ms, ~19 req/min), never exceeding LOC's 20 per minute. A call that cannot start in time fails asserver_busywithretryAfterRate-limit handling: a 429 triggers LOC's 1-hour block, and calls fail without sending anything until it lifts (never retried); a Cloudflare challenge or HTML page instead of JSON fails as
upstream_unavailablewithretryAfter: 60.libofcongress_search_subjects(id.loc.gov) is unaffectedA 50-second budget per tool call covers queue wait, retries, and the OCR or transcription fetch, so a slow upstream fails as
request_timed_out, which on thewww.loc.govtools is retryable with a recovery that leads with one unchanged retry; other upstream failures (dropped connections, any other error status, empty or truncated bodies) fail asupstream_unavailablewith a retry hintPages past the end of the results or past the retrieval ceiling return an empty result with a notice, not an error
Newspaper OCR is surfaced as-is; 19th-century or degraded pages may contain garbled text
Agent-friendly output:
Empty results include a
noticewith recovery hints that echo the applied filtersItem and newspaper searches carry pagination status (
total,page,pages,has_next), capped at LOC's ~100,000-item retrieval ceiling; subject searches useoffsetandnext_offsetwith a page-localtotalocr_availableandis_itemlet callers branch without parsing textEvery typed error carries a recovery hint
Getting started
Connect Claude Code to the hosted server:
claude mcp add --transport http libofcongress-mcp-server https://libofcongress.caseyjhand.com/mcpOr run it locally:
claude mcp add libofcongress-mcp-server -- npx -y @cyanheads/libofcongress-mcp-serverFor other clients, add this to the MCP config file:
{
"mcpServers": {
"libofcongress-mcp-server": {
"command": "npx",
"args": ["-y", "@cyanheads/libofcongress-mcp-server"]
}
}
}No API key is required. Set LOC_USER_AGENT to identify your application to LOC. For Docker or a source build, see Running the server.
Configuration
All configuration is validated at startup via Zod schemas in src/config/server-config.ts.
Variable | Description | Default |
| User-Agent header sent with LOC API requests. LOC recommends a descriptive value for polite access. |
|
| Delay in milliseconds between LOC API requests to stay under the 20 req/min rate limit. |
|
| Transport: |
|
| Port for HTTP server. |
|
| Auth mode: |
|
| HTTP session mode. This server is explicitly stateless. |
|
| Log level (RFC 5424). |
|
| Directory for log files (Node.js only). |
|
| Log each failed tool call's arguments and result, redacted by key name and capped at |
|
| Storage backend. |
|
| Enable OpenTelemetry instrumentation (spans, metrics, completion logs). |
|
See .env.example for the full list of optional overrides.
Running the server
Local development
Requires Bun v1.4.4 or higher (or Node.js v24+).
git clone https://github.com/cyanheads/libofcongress-mcp-server.git
cd libofcongress-mcp-server && bun install
cp .env.example .env
# Optionally set LOC_USER_AGENT or LOC_REQUEST_DELAY_MS.Build and run:
# One-time build bun run rebuild # Run the built server bun run start:stdio # or bun run start:httpRun checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite bun run lint:mcp # Validate MCP definitions against spec
Docker
docker run --rm -p 3010:3010 ghcr.io/cyanheads/libofcongress-mcp-server:latestThe image defaults to HTTP transport, stateless session mode, and logs to /var/log/libofcongress-mcp-server. For stdio in an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/libofcongress-mcp-server:latest"]. Build locally with docker build -t libofcongress-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
Directory | Purpose |
|
|
| Server-specific environment variable parsing ( |
| Tool definitions ( |
| Resource definitions — |
|
|
|
|
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storageRegister new tools and resources via the arrays in
src/index.tsWrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks and tests before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Chronicling America MCP — full-text search of ~150 years of digitized U.S. newspapers…
Search extracted newspaper articles from the Library of Congress, 1736-1963. Subscription required.
Library of Congress (loc.gov) MCP — the world's largest library.
Search US lobbying disclosures and foreign-agent registrations via MCP.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceProvides access to the Library of Congress (loc.gov) data, enabling AI agents to search and retrieve information from the world's largest library.11 npmMIT
- AlicenseAqualityDmaintenanceEnables searching and retrieving historical records from the Library of Congress, including newspapers, photos, maps, manuscripts, audio, and film, via the Model Context Protocol.101MIT
- AlicenseAqualityCmaintenanceMCP server for searching and retrieving full-text pages from the Library of Congress, including newspapers, books, and manuscripts, via the loc.gov API.3Apache 2.0
- AlicenseAqualityBmaintenanceAn MCP server for the Library of Congress that enables searching scanned American newspaper pages, searching catalogue items by media type, reading individual records, and listing digital collections, all without requiring an API key or account.4211 npmMIT