mcp-libraryofcongress

# mcp-libraryofcongress

[![npm](https://img.shields.io/npm/v/mcp-libraryofcongress.svg)](https://www.npmjs.com/package/mcp-libraryofcongress)
[![CI](https://github.com/smeet666/mcp-libraryofcongress/actions/workflows/ci.yml/badge.svg)](https://github.com/smeet666/mcp-libraryofcongress/actions/workflows/ci.yml)
[![license](https://img.shields.io/npm/l/mcp-libraryofcongress.svg)](LICENSE)
[![Glama](https://glama.ai/mcp/servers/smeet666/mcp-libraryofcongress/badges/score.svg)](https://glama.ai/mcp/servers/smeet666/mcp-libraryofcongress)

An MCP server for the [Library of Congress](https://www.loc.gov). **Search the
text scanned off digitised American newspaper pages**, search the catalogue by
kind of thing, read one record, and list the collections a curator built. No API
key, no account, no configuration.

_(Version française plus bas / French version below)_

## Quickstart

**One-click install**

[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=libraryofcongress&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1saWJyYXJ5b2Zjb25ncmVzcyJdfQ%3D%3D)
[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install-0098FF?style=flat&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=libraryofcongress&config=%7B%22name%22%3A%22libraryofcongress%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-libraryofcongress%22%5D%7D)

**Claude Code**

```bash
claude mcp add libraryofcongress -- npx -y mcp-libraryofcongress
```

**Claude Desktop, Cursor, and any client using the standard config format**

```json
{
  "mcpServers": {
    "libraryofcongress": {
      "command": "npx",
      "args": ["-y", "mcp-libraryofcongress"]
    }
  }
}
```

Node 20 or later.

**Bundle, without npm**

Download `mcp-libraryofcongress-<version>.mcpb` from
[the latest release](https://github.com/smeet666/mcp-libraryofcongress/releases/latest)
and open it. A client that supports MCP bundles installs it on its own, with no
npm and no configuration file to edit.

## Tools

| Tool                | What it does                                              | Key parameters                                            |
| ------------------- | --------------------------------------------------------- | --------------------------------------------------------- |
| `search_newspapers` | Finds a phrase in the text of scanned newspaper pages.    | `query`, `location`, `publication`, `year_from`, `limit`  |
| `search_items`      | Searches one catalogue: books, photos, maps, audio, more. | `query`, `media_type`, `subject`, `location`, `year_from` |
| `get_item`          | Reads one record, section by section.                     | `identifier`, `sections`, `offset`                        |
| `list_collections`  | The digital collections, with the filter each one takes.  | `limit`, `page`, `max_description_chars`                  |

The server is **read-only**. It uploads nothing and writes nothing back.

## Searching inside the newspapers is the point

A catalogue search reads titles, creators and descriptions. `search_newspapers`
reads what optical character recognition took off millions of scanned pages of
American newspapers, so it answers a question nothing else here can: _which
issue printed this phrase_. A match comes back with the paper, the date, the
leaf of the issue, the state it was published in, and an address that opens that
leaf with the query applied.

Put a phrase in double quotes to match it whole. Without quotes the words are
matched separately, which finds far more.

The corpus spans every state and a century and a half, so a bare phrase reaches
a great deal that a question did not ask for. Three arguments narrow it:
`location` keeps to papers published in one state, `publication` to a single
paper, and `year_from` with `year_to` to a span of years. Each takes the wording
the Library itself uses, which every match carries: `state` on a row is what
`location` expects, and `publication` on a row is what `publication` expects.
Asking `search_items` with `media_type: "newspapers"` lists the papers
themselves, and a title there is the wording too.

```
search_newspapers(
  query: '"ellis island" immigration',
  location: "new york",
  publication: "new-york tribune (new york [n.y.]) 1866-1924",
  year_from: 1900, year_to: 1910
)
```

A filter the corpus does not recognise matches nothing, and an empty answer
would read as the Library holding no such page. The search is asked again
without the narrowing instead, and a note says what was set aside.

### Three things it will not pretend to know

**`total` counts pages, and it pages.** It is the number of newspaper leaves
that match, and it is not a count of how many times the words occur. Ask for
page 2, 3 and so on rather than treating the first answer as the whole of it.

**An excerpt is sometimes the opening of the page.** The Library returns the
beginning of a page's text with each row rather than the whole page, so the
searched words are often further down than that text reaches. `words_located`
says which of the two happened: true and the passage is centred on the words,
false and it is the opening of the leaf. Follow `source_url` for the rest.

**Scanned text is machine-read.** Excerpts carry the misreadings that come with
it. Quote them as scanned text and link the page.

## One catalogue per kind of thing

`search_items` requires `media_type`, because the Library keeps a separate
catalogue for each kind of thing: `books`, `photos`, `maps`, `audio`,
`film-and-videos`, `manuscripts`, `notated-music`, `newspapers`. There is no
address that asks all of them at once, and one title can exist in several.

Narrowing is typed rather than free text: `year_from`, `year_to`, `subject`,
`location`, `language`, `collection`, `online_only`, `sort`. A filter that
matches nothing is set aside, the search is asked again without it, and the
answer names what was dropped, so a narrowing that spelled a subject the Library
words differently is reported as a spelling that found nothing rather than as
the Library holding nothing on it.

By default only material with a digitised copy comes back. `online_only: false`
takes in the records the Library holds on a shelf alone.

## Reading a record, and finding a corpus

`get_item` takes one identifier. An identifier can carry slashes: a single
newspaper issue is named by its paper, its date and its edition together, as in
`sn83045462/1929-02-03/ed-1`. Sections are opt-in, `basic`, `citations`,
`resources` and `full_metadata`, because the served copies of a scan and the
full field list are each larger than the record they describe. A long
description paginates by character offset and resumes at a line boundary: when
`next_offset` is not null, call again with `offset` set to it.

`list_collections` shows the bodies of material a curator chose, described and
published together, so a caller can see what is there before searching. Each row
carries `collection_filter`, which is the wording `search_items` takes as its
`collection` argument.

## What the answers claim

**A failure is never an empty result.** A refused request is `invalid_input`, an
unreadable answer is `parse_failure`, and only a genuinely empty record is an
absence. Silence about a failure becomes "there is none" in the mouth of a
model, which is a false statement about the world.

**A null is never printed as a value.** A record with no stated terms of use
reports null and says that silence is not permission.

**A count is named for what it counts.** The site reports the number of results
and the number of pages under names that read alike, and one is the other
multiplied by the page size. Only the count of results is ever published as a
total.

**Every answer carries a link back**, and the notes that qualify an answer reach
the text block, so a client that renders only text still reads them. Text
published by someone else cannot imitate this server's own lines.

## Rights

Metadata from the Library of Congress is in the public domain. The material it
describes is not always: rights vary per deposit and are often unstated. A
record reports the terms it carries, and a record carrying none is not a record
granting permission. Credit the Library of Congress and link what you use.

## Configuration

Every variable is optional. Set them in the `env` block of your MCP client.

| Variable                   | Default  | Purpose                                                                                                                                                   |
| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOC_USER_AGENT`           | _(none)_ | Identify your own client. The project's identifier is appended, so the Library can reach a human.                                                         |
| `LOC_MIN_INTERVAL_MS`      | `6000`   | Minimum gap between requests. Values below 3000 ms are refused, as are values above 60000.                                                                |
| `LOC_TIMEOUT_MS`           | `30000`  | Per-request deadline for the catalogue, the records and the collections. Accepted between 1000 and 120000.                                                |
| `LOC_NEWSPAPER_TIMEOUT_MS` | `90000`  | Per-request deadline for `search_newspapers`, which reads the text of millions of pages and answers in tens of seconds. Accepted between 1000 and 300000. |
| `LOC_MAX_RETRIES`          | `3`      | Retries on rate limiting and transient errors, up to 8.                                                                                                   |
| `LOC_CACHE_TTL_MS`         | `900000` | In-memory cache lifetime. `0` turns it off.