mcp-archiveorg

# mcp-archiveorg

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

An MCP server for the Internet Archive. **Search the text inside digitised
books**, browse the catalogue, and read Wayback Machine captures. 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=archiveorg&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC1hcmNoaXZlb3JnIl19%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=archiveorg&config=%7B%22name%22%3A%22archiveorg%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-archiveorg%22%5D%7D)

**Claude Code**

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

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

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

**Bundle, without npm**

Download `mcp-archiveorg-<version>.mcpb` from
[the latest release](https://github.com/smeet666/mcp-archiveorg/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_inside`  | Finds a phrase in the text of scanned pages.           | `query`, `limit`, `page`                              |
| `search_items`   | Searches the catalogue: films, books, audio, software. | `query`, `media_type`, `sort`                         |
| `get_item`       | Reads one record, section by section.                  | `identifier`, `sections`, `file_format`               |
| `get_snapshot`   | The Wayback capture closest to a date.                 | `url`, `at`                                           |
| `list_snapshots` | Captures of a page, oldest first.                      | `url`, `limit`, `cursor`                              |
| `search_books`   | A work on Open Library, by name or by criteria.        | `query`, `subject`, `place`, `time`, `person`, `sort` |

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

## Finding a book you cannot name

`search_books` takes a title or an author. It equally takes the shape of a book
in place of its name: what it is catalogued under, where it is set, the period it
treats, who it is about, how long it runs, when it first appeared. The criteria
combine, and `sort` by rating or by readers answers which of the matches is
worth reading.

Asking for works on grief, in English, under 250 pages, first published between
2000 and 2020, ordered by how many readers recorded them, returns _A Monster
Calls_ and _The Tiger Rising_ rather than a list of books with "grief" in the
title. The page count comes back on every row, because filtering on a number the
answer never shows would be a promise it cannot keep.

## Searching inside the books is the point

A catalogue search reads titles and descriptions. `search_inside` reads what
optical character recognition took off millions of scanned pages, so it answers
a question nothing else here can: _which book contains this phrase_. A match
comes back with the item, the passage around the phrase, and a link.

### Three things it will not pretend to know

**There is no page number.** The index reports where the search text sits
inside the item, which is `1` on nearly every match. It is not a leaf of the
book. Nothing here publishes a page, and no link claims one: a citation naming
a page the index does not know is worse than a citation naming none.

**`total` counts documents, and it pages.** It is not a number of occurrences.
The last page of a match set is shorter than the first and the one after it is
empty, so read past page 1 rather than treating the first answer as the whole
of it.

**A title can describe the container.** An item can bundle several documents,
and a match inside one of them carries the item's title, creator and year.
`inside_container` says when that happened, and `matched_file` names what
actually holds the passage.

## Other things worth knowing

**A capture is rarely on the date you asked for.** `get_snapshot` always
reports `days_from_requested`, because the closest capture of a quiet site can
be years away. A page asked for in March 1994 can answer with December 1996.

**The capture index is slow, and it has no offset.** Tens of seconds on a busy
address, and it ignores an offset entirely. It pages by a key it hands back:
pass `next_cursor` as `cursor`, and a null one means the end of the history.

**A catalogue search matches descriptions too.** A compilation whose notes
mention a name ranks alongside that person's own work. Read `creator` before
attributing a result.

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

**Nothing states what may be reused.** Many items carry no licence at all, and
the Archive holds material under every possible term. `get_item` says so rather
than letting silence read as permission.

## Configuration

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

| Variable                | Default                | Purpose                                                                                                  |
| ----------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------- |
| `IA_USER_AGENT`         | _(project identifier)_ | Identify your own client. The project's identifier is appended, so the Archive can always reach a human. |
| `IA_MIN_INTERVAL_MS`    | `1000`                 | Minimum gap between requests. Values below 500 ms are refused.                                           |
| `IA_TIMEOUT_MS`         | `20000`                | Per-request deadline.                                                                                    |
| `IA_HISTORY_TIMEOUT_MS` | `60000`                | Deadline for the capture index, which is slow by design.                                                 |
| `IA_MAX_RETRIES`        | `3`                    | Retries on rate limiting and transient errors.                                                           |
| `IA_CACHE_TTL_MS`       | `900000`               | In-memory cache lifetime. `0` turns it off.                                                              |
| `IA_CACHE_MAX_ENTRIES`  | `200`                  | In-memory cache size.                                                                                    |
| `IA_LOG_LEVEL`          | `error`                | `silent`, `error`, `info` or `debug`. Logs go to stderr.                                                 |

## How this server treats the Archive

The Internet Archive is a non-profit that charges nobody and turns nobody away.
This server paces itself to one request at a time with a gap that configuration
can widen but never narrow past half a second, widens it further when the site
pushes back, caches what it reads, and identifies itself with an address a human
can be reached at. A caller may say who they are; that address is appended
rather than replaced.

`archive.org/robots.txt` disallows only `/control/` and `/report/`, neither of
which is touched here. No route used requires a key, and none of them is
documented: they are the routes the Archive's own pages call, which is why the
nightly canary matters more here than it would against a published API.

## Troubleshooting

**`rate_limited`.** The Archive asked this client to slow down. It never means
the thing you asked for is missing.

**`invalid_input` on a search.** The query was refused rather than answered.
An unbalanced quotation mark, bracket or colon is read as an operator.

**`parse_failure`.** A response arrived in a shape this server cannot read,
which usually means a route changed. Please
[open an issue](https://github.com/smeet666/mcp-archiveorg/issues) with the
arguments you used.

## Development

```bash
npm install
npm test                 # unit tests, no network
npm run typecheck
npm run build
IA_LIVE=1 npm run test:live   # one request per route against the real site
npm run inspector        # explore the tools in the MCP Inspector
```

Fixtures are generated rather than captured: `npm run build:fixtures` writes a
corpus of invented titles and passages, so tests are deterministic and no
Archive content lives in this repository.

The access layer under `src/ia` does not import the MCP SDK and is published
separately as `mcp-archiveorg/client`, usable as a plain library.

## Contributing

Bugs, questions and ideas all belong in
[the issue tracker](https://github.com/smeet666/mcp-archiveorg/issues).
Pull requests are welcome; please open an issue first so we can agree on what
the right answer is before you write it. [CONTRIBUTING.md](CONTRIBUTING.md) has
the detail, and [SECURITY.md](SECURITY.md) covers anything exploitable.

## Support

Free, and it stays free. If it saved you some time, you can
[buy me a coffee](https://buymeacoffee.com/smeet666).

## License

MIT.