mcp-archiveorg

mcp-archiveorg

An MCP server for the Internet Archive. Search the text inside digitisedbooks, browse the catalogue, and read Wayback Machine captures. No API key, noaccount, no configuration.

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

Quickstart

One-click install

Claude Code

claude mcp add archiveorg -- npx -y mcp-archiveorg

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

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

Bundle, without npm

Download mcp-archiveorg-<version>.mcpb fromthe latest releaseand open it. A client that supports MCP bundles installs it on its own, with nonpm and no configuration file to edit.

Tools

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

Searching inside the books is the point

A catalogue search reads titles and descriptions. search_inside reads whatoptical character recognition took off millions of scanned pages, so it answersa question nothing else here can: which book contains this phrase. A matchcomes 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 sitsinside the item, which is 1 on nearly every match. It is not a leaf of thebook. Nothing here publishes a page, and no link claims one: a citation naminga 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 isempty, so read past page 1 rather than treating the first answer as the wholeof 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 whatactually holds the passage.

Other things worth knowing

A capture is rarely on the date you asked for. get_snapshot alwaysreports days_from_requested, because the closest capture of a quiet site canbe 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 busyaddress, 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 notesmention a name ranks alongside that person's own work. Read creator beforeattributing a result.

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

Nothing states what may be reused. Many items carry no licence at all, andthe Archive holds material under every possible term. get_item says so ratherthan letting silence read as permission.

Configuration

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

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 configurationcan widen but never narrow past half a second, widens it further when the sitepushes back, caches what it reads, and identifies itself with an address a humancan be reached at. A caller may say who they are; that address is appendedrather than replaced.

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

Troubleshooting

rate_limited. The Archive asked this client to slow down. It never meansthe 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. Pleaseopen an issue with thearguments you used.

Development

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 acorpus of invented titles and passages, so tests are deterministic and noArchive content lives in this repository.

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

Contributing

Bugs, questions and ideas all belong inthe issue tracker.Pull requests are welcome; please open an issue first so we can agree on whatthe right answer is before you write it. CONTRIBUTING.md hasthe detail, and SECURITY.md covers anything exploitable.

Support

Free, and it stays free. If it saved you some time, you canbuy me a coffee.

License

MIT. See LICENSE. The licence covers this source code only, not thematerial retrieved through it, which carries whatever terms its depositorattached, and often none at all.

This is an unofficial project, with no affiliation to or endorsement by theInternet Archive.

mcp-archiveorg (français)

Un serveur MCP pour l'Internet Archive. Cherchez une phrase dans le texte deslivres numérisés, parcourez le catalogue, et lisez les captures de la WaybackMachine. Sans clé d'API, sans compte, sans configuration.

Démarrage rapide

Installation en un clic

Claude Code

claude mcp add archiveorg -- npx -y mcp-archiveorg

Claude Desktop, Cursor, et tout client utilisant le format standard

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

Bundle, sans npm

Téléchargez mcp-archiveorg-<version>.mcpb depuisla dernière releaseet ouvrez-le. Un client compatible l'installe seul, sans npm ni fichier deconfiguration à modifier.

Outils

Le serveur est en lecture seule. Il ne téléverse rien et n'écrit rien.

Chercher à l'intérieur des livres est le cœur du sujet

Une recherche de catalogue lit les titres et les descriptions. search_insidelit ce que la reconnaissance de caractères a tiré de millions de pagesnumérisées, et répond donc à une question qu'aucun autre outil ici ne saittraiter : quel livre contient cette phrase.

Trois choses qu'il refuse de prétendre savoir

Il n'y a pas de numéro de page. L'index indique où se situe le textecherchable dans l'élément, ce qui vaut 1 sur presque toutes lescorrespondances. Ce n'est pas un feuillet du livre. Rien ici ne publie de page,et aucun lien n'en revendique : une citation qui nomme une page que l'indexignore est pire qu'une citation qui n'en nomme aucune.

total compte des documents, et il se pagine. Ce n'est pas un nombred'occurrences. Lisez au-delà de la page 1 plutôt que de prendre la premièreréponse pour la totalité.

Un titre peut décrire le contenant. Un élément peut regrouper plusieursdocuments. inside_container le signale, et matched_file nomme celui quiporte réellement le passage.

Autres points utiles

Une capture tombe rarement sur la date demandée. get_snapshot annoncetoujours days_from_requested : la capture la plus proche d'un site peu visitépeut être à des années.

L'index des captures est lent, et n'a pas d'offset. Il l'ignorecomplètement. Il se parcourt avec la clé qu'il renvoie : repassez next_cursoren cursor, et une valeur nulle marque la fin de l'histoire.

La recherche catalogue lit aussi les descriptions. Une compilation citant unnom se classe à côté des disques de cette personne. Vérifiez creator avantd'attribuer un résultat.

Le texte numérisé est lu par une machine. Les extraits en portent lesfautes. Citez-les comme tels et suivez le lien.

Rien n'indique ce qui est réutilisable. Beaucoup d'éléments ne portentaucune licence. get_item le dit, plutôt que de laisser le silence passer pourune permission.

Configuration

Toutes les variables sont optionnelles, à déclarer dans le bloc env de votreclient.

Ce que ce serveur doit à l'Archive

L'Internet Archive est une association qui ne facture rien et ne refusepersonne. Ce serveur se limite à une requête à la fois, avec un écart que laconfiguration peut élargir mais jamais réduire sous la demi-seconde, l'élargitencore quand le site demande de l'air, met en cache ce qu'il lit, et s'identifieavec une adresse où joindre une personne. Un appelant peut dire qui il est ;cette adresse est ajoutée, pas remplacée.

Le robots.txt d'archive.org n'interdit que /control/ et /report/, dontaucun n'est touché ici. Aucune route utilisée n'exige de clé, et aucune n'estdocumentée : ce sont celles qu'appellent les pages du site, ce qui rend lecanari nocturne plus important ici que face à une API publiée.

Dépannage

rate_limited. L'Archive demande à ce client de ralentir. Cela ne signifiejamais que ce que vous cherchez est absent.

invalid_input sur une recherche. La requête a été refusée, pas répondue.Un guillemet, un crochet ou un deux-points non équilibré est lu comme unopérateur.

parse_failure. Une réponse est arrivée dans une forme illisible pour ceserveur, ce qui signale en général qu'une route a changé. Mercid'ouvrir une issue.

Développement

npm install
npm test                 # tests unitaires, sans réseau
npm run typecheck
npm run build
IA_LIVE=1 npm run test:live   # une requête par route sur le vrai site
npm run inspector        # explorer les outils dans le MCP Inspector

Les fixtures sont générées, pas capturées : npm run build:fixtures écrit uncorpus de titres et de passages inventés, ce qui rend les tests déterministes etévite de stocker du contenu de l'Archive dans ce dépôt.

La couche d'accès sous src/ia n'importe pas le SDK MCP et est publiéeséparément sous mcp-archiveorg/client, utilisable comme bibliothèque.

Contribuer

Bugs, questions et idées vont dansle suivi d'issues. Lespull requests sont bienvenues ; ouvrez d'abord une issue pour qu'on s'accordesur la bonne réponse avant que vous n'écriviez le code.

Soutenir

Gratuit, et ça le reste. Si ça vous a fait gagner du temps, vous pouvezm'offrir un café.

Licence

MIT, voir LICENSE. La licence couvre uniquement ce code source, pasles documents récupérés par son intermédiaire, qui portent les conditions queleur déposant y a attachées, et souvent aucune.

Projet non officiel, sans affiliation à l'Internet Archive ni approbation de sapart.