@cyanheads/libofcongress-mcp-server

Public Hosted Server: https://libofcongress.caseyjhand.com/mcp

Overview

Library of Congress digital collections, Chronicling America newspaper archives, and LC Subject Headings (LCSH) authority data. Search items and newspaper pages, retrieve full item metadata and OCR text, resolve LCSH subject terms, and browse curated collections from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Resources

All resource data is also reachable via libofcongress_get_item. Use libofcongress_search to discover item IDs first.

Related MCP server: historical-investigator-mcp

Capability reference

libofcongress_search tool

• Filters: eight material formats (photo, map, newspaper, manuscript, audio, film, book, notated-music), inclusive year range (date_start/date_end), LCSH subject (exact spelling from libofcongress_search_subjects), location, and collection_slug (from libofcongress_browse_collections, mutually exclusive with format); up to 100 results per page

• Each result carries is_item — true for catalog items whose id resolves via libofcongress_get_item, false for collections, exhibit/guide pages, and newspaper pages, whose url should be opened instead

libofcongress_get_item tool

• Takes a search result's id verbatim, simple or multi-segment (newspaper pages: sn95047246/1935-09-05/ed-1); returns contributors with their roles, LCSH subject headings, notes, summary, languages, locations, rights, physical description, call number, former IDs, formats, and access_restricted

• resource_links carries downloadable file URLs (TIFF/JPEG/PDF) and related_items related record IDs or URLs, both in full; fields absent upstream are omitted rather than filled

libofcongress_search_newspapers tool

• Filters: keyword, inclusive date range, US state (full name), and newspaper title (partial match); up to 100 results per page

• Each result carries a ~500-character OCR excerpt for relevance assessment, states (every state LOC indexes the title under), and the url that libofcongress_get_newspaper_page takes verbatim

libofcongress_get_newspaper_page tool

• Takes the url from a libofcongress_search_newspapers result; anything outside https://www.loc.gov/resource/ is rejected as invalid_page_url before any request

• Returns ocr_text with the issue's newspaper_title, date, place_of_publication, states, edition, the page's sequence, and the issue's segment_count; ocr_available: false marks an image-only page, and a notice flags a page whose OCR exists but did not come back

libofcongress_search_subjects tool

• Keyword query, up to 50 results per call (default 10); returns LCSH label and stable LOC uri — pass the label verbatim as libofcongress_search's subject filter, since LCSH uses inverted forms ("Photography, Aerial", "World War, 1939-1945")

• When id.loc.gov's ranked suggest pool, rather than a lack of coverage, yields an empty or short result, the response says so with a recovery hint

libofcongress_browse_collections tool

• Optional keyword filter on collection name and description; up to 100 collections per page

• Each collection carries a slug for libofcongress_search's collection_slug (taken from the loc.gov route, not derivable from the title); item_count is approximate and omitted when LOC doesn't provide it

libofcongress://item/{+item_id} resource

• Returns the same full record as libofcongress_get_item, as application/json

• item_id comes from a libofcongress_search result's id field, or from libofcongress_get_item

• Multi-segment newspaper IDs keep their slashes intact (e.g. libofcongress://item/sn95047246/1935-09-05/ed-1); percent-encoded slashes (%2F) also resolve

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:

• Module-level rate-limit enforcement: 20 req/min limit; 429 responses trigger a 1-hour block, and the error's recovery hint counts down the minutes left and names the time it lifts

• Configurable pacing delay (default 3100ms, ~19 req/min) applied before every outbound LOC API request

• HTML-response detection guards against silent rate-limit proxy pages that return 200 with HTML

• Out-of-range page handling: a page past the end of the results (HTTP 404 on any page after the first) or past the retrieval ceiling (HTTP 400) returns an empty result with a notice, not an error — both point back to page 1 for the real page count, and the ceiling notice also explains how to partition a search that matches more than LOC will page through

• Transient-fault resilience: network drops and timeouts retry with backoff behind a 30s per-request timeout ceiling; the 429 rate-limit path is never retried, since a retry would deepen LOC's 1-hour block

• Newspaper OCR is surfaced as-is: quality varies by digitization batch and era, and 19th-century or degraded pages may contain garbled text

Agent-friendly output:

• Empty results always include a notice field with recovery hints — echoes the applied filters and suggests how to broaden

• Pagination status on every search response (total, page, pages, has_next), capped at LOC's ~100,000-item retrieval ceiling, with a notice disclosing how to page past it

• ocr_available and is_item discriminator fields let callers branch on data availability without parsing text

• Recovery hints on every typed error contract — actionable next steps for the agent on every failure mode

Getting started

Public Hosted Instance

A public instance is available at https://libofcongress.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "streamable-http",
      "url": "https://libofcongress.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add the following to your MCP client configuration file.

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/libofcongress-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_SESSION_MODE": "stateless",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/libofcongress-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_SESSION_MODE": "stateless",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "libofcongress-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "MCP_SESSION_MODE=stateless",
        "ghcr.io/cyanheads/libofcongress-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

• No API key required — the LOC JSON API and LC Linked Data endpoints are open. LOC recommends a descriptive LOC_USER_AGENT for polite access.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/libofcongress-mcp-server.git

2. Navigate into the directory:

cd libofcongress-mcp-server

3. Install dependencies:

bun install

4. Configure environment:

cp .env.example .env
# edit .env if you want to set LOC_USER_AGENT or LOC_REQUEST_DELAY_MS

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts.

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http

• Run 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 build -t libofcongress-mcp-server .
docker run --rm -p 3010:3010 libofcongress-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/libofcongress-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic

• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage

• Register new tools and resources via the arrays in src/index.ts

• Wrap 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 test

License

Apache-2.0 — see LICENSE for details.