Search the Wayback Machine and IA library (40M+ items), fetch archived snapshots, retrieve item metadata and full text via MCP. STDIO or Streamable HTTP.\n
\n\n[](https://github.com/cyanheads/internet-archive-mcp-server/releases/latest/download/internet-archive-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=internet-archive-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvaW50ZXJuZXQtYXJjaGl2ZS1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22internet-archive-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Finternet-archive-mcp-server%22%5D%7D)\n\n[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)\n\n
\n\n---\n\n## Tools\n\nFive tools covering two Internet Archive pillars — Wayback Machine snapshot discovery and retrieval, and IA library search and content access:\n\n| Tool | Description |\n|:---|:---|\n| `ia_find_snapshots` | Find Wayback Machine snapshots of a URL. Mode `closest` returns the nearest capture to a given timestamp. Mode `history` returns the full capture list via CDX with date range, status, and MIME filters, collapsed by default to one capture per day. Supports resume-key pagination for large histories. |\n| `ia_get_snapshot` | Fetch the archived content of a URL at a specific Wayback timestamp. Strips HTML to readable text and returns the canonical replay URL. |\n| `ia_search_items` | Search the IA library (40M+ items). Filter by media type, collection, creator, date range, and language. Sort by relevance, date, or downloads. Returns identifiers, titles, types, and pagination context (`total_found`, `page`, `rows`). |\n| `ia_get_item` | Retrieve full metadata and the file manifest for an Archive item by identifier — title, creator, description, subjects, collections, license, and every file with its format, size, and direct download URL. |\n| `ia_get_text` | Retrieve readable OCR text (DjVuTXT or plain-text) from a text item. Length-aware truncation with continuation pointer (`char_offset`) for paging through large documents. |\n\n### `ia_find_snapshots`\n\nDiscover what the Wayback Machine has captured for any URL.\n\n- **`closest` mode**: single fast lookup via the Availability API — returns the nearest capture to a given timestamp\n- **`history` mode**: full capture list via the CDX API, filterable by date range (`from`/`to`), HTTP status (`status_filter`), and MIME type\n- Default collapse of `timestamp:8` (one capture per day) keeps responses tractable for popular URLs; adjust with the `collapse` parameter (`timestamp:N`, N=1–14)\n- Resume-key pagination (`resume_key`) for stepping through large CDX histories without re-scanning\n\n---\n\n### `ia_get_snapshot`\n\nRetrieve what a page actually said at a point in time.\n\n- Resolves to the nearest available capture when the exact timestamp has no snapshot\n- Strips Wayback banner injections and extracts readable text — returns clean content alongside the canonical replay URL for browser access\n- Useful for fact-checking, citation verification, and tracing how content changed over time\n\n---\n\n### `ia_search_items`\n\nSearch across 40M+ Archive items by keyword and metadata filters.\n\n- Full-text Solr query syntax plus structured filters: `mediatype` (texts, audio, video, software, image), `collection`, `creator`, `language`, and date range\n- Sort by relevance, date added, or download count\n- Pagination via `page` and `rows`; output includes `total_found` and current `page`/`rows` so agents can paginate correctly without guessing\n\n---\n\n### `ia_get_item`\n\nFetch the complete metadata and file manifest for any Archive item.\n\n- Returns structured fields: `title`, `creator`, `description`, `subjects`, `collections`, `date`, `license`, and more\n- `files[]` includes every file in the item with its `format`, `size`, and direct download URL — the primary way to act on a search result\n- `metadata` response `{}` on unknown identifier → typed `item_not_found` error\n\n---\n\n### `ia_get_text`\n\nRead the OCR text of public-domain books, documents, and transcripts.\n\n- Locates the best available text file in the item's manifest (DjVuTXT preferred, falls back to plain text)\n- `max_chars` and `char_offset` enable efficient paging through long documents without re-fetching\n- Surfaces `download_forbidden` (HTTP 403) as a typed error for restricted collections rather than failing silently\n\n## Resource\n\n| Type | Name | Description |\n|:---|:---|:---|\n| Resource | `ia://item/{identifier}` | Metadata snapshot for an Archive item — title, creator, mediatype, description, subjects, collections, date, license, and file count. Stable URIs for injectable context. |\n\nAll resource data is also reachable via `ia_get_item`. The resource provides a stable, injectable URI for referencing a specific item across workflows.\n\n## Features\n\nBuilt on [`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core):\n\n- Declarative tool, resource, and prompt definitions — single file per primitive, framework handles registration and validation\n- Unified error handling — handlers throw, framework catches, classifies, and formats\n- Pluggable auth: `none`, `jwt`, `oauth`\n- Swappable storage backends: `in-memory`, `filesystem`, `Supabase`, `Cloudflare KV/R2/D1`\n- Structured logging with optional OpenTelemetry tracing\n- STDIO and Streamable HTTP transports\n\nInternet Archive-specific:\n\n- No credentials required — all four APIs are public\n- Three service layers: `WaybackService` (Availability + CDX), `ArchiveSearchService` (Solr), `ArchiveMetadataService` (Metadata + downloads)\n- CDX collapse-by-day default and configurable `limit` keep responses tractable for high-capture URLs\n- Identifies User-Agent on every request as required by IA's terms; configurable via `IA_USER_AGENT`\n\nAgent-friendly output:\n\n- Pagination context on every list response — `total_found`, `page`, `rows` (search) and `resume_key` (CDX history) so agents never have to guess whether results are complete\n- Typed error reasons (`no_snapshots`, `no_snapshot_available`, `item_not_found`, `no_text_file`, `download_forbidden`) with recovery hints so callers can retry or explain to users without parsing text\n- Structured file manifests — every `ia_get_item` response includes file-level metadata (format, size, URL) enabling agents to select the right file without a follow-up call\n\n## Getting started\n\nNo API key required — the Internet Archive's APIs are fully public.\n\nAdd the following to your MCP client configuration file:\n\n```json\n{\n \"mcpServers\": {\n \"internet-archive-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"bunx\",\n \"args\": [\"@cyanheads/internet-archive-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with npx (no Bun required):\n\n```json\n{\n \"mcpServers\": {\n \"internet-archive-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@cyanheads/internet-archive-mcp-server@latest\"],\n \"env\": {\n \"MCP_TRANSPORT_TYPE\": \"stdio\",\n \"MCP_LOG_LEVEL\": \"info\"\n }\n }\n }\n}\n```\n\nOr with Docker:\n\n```json\n{\n \"mcpServers\": {\n \"internet-archive-mcp-server\": {\n \"type\": \"stdio\",\n \"command\": \"docker\",\n \"args\": [\n \"run\", \"-i\", \"--rm\",\n \"-e\", \"MCP_TRANSPORT_TYPE=stdio\",\n \"ghcr.io/cyanheads/internet-archive-mcp-server:latest\"\n ]\n }\n }\n}\n```\n\nFor Streamable HTTP, set the transport and start the server:\n\n```sh\nMCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http\n# Server listens at http://localhost:3010/mcp\n```\n\n### Prerequisites\n\n- [Bun v1.3.0](https://bun.sh/) or higher (or Node.js v24+).\n- No external accounts or API keys required.\n\n### Installation\n\n1. **Clone the repository:**\n\n```sh\ngit clone https://github.com/cyanheads/internet-archive-mcp-server.git\n```\n\n2. **Navigate into the directory:**\n\n```sh\ncd internet-archive-mcp-server\n```\n\n3. **Install dependencies:**\n\n```sh\nbun install\n```\n\n4. **Configure environment:**\n\n```sh\ncp .env.example .env\n# Optional: edit .env for custom User-Agent, timeouts, etc.\n```\n\n## Configuration\n\nAll configuration is validated at startup via Zod schemas in `src/config/server-config.ts`.\n\n| Variable | Description | Default |\n|:---------|:------------|:--------|\n| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http` | `stdio` |\n| `MCP_HTTP_PORT` | HTTP server port | `3010` |\n| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth` | `none` |\n| `MCP_LOG_LEVEL` | Log level (`debug`, `info`, `notice`, `warning`, `error`) | `info` |\n| `LOGS_DIR` | Directory for log files (Node.js only) | `/logs` |\n| `STORAGE_PROVIDER_TYPE` | Storage backend | `in-memory` |\n| `OTEL_ENABLED` | Enable OpenTelemetry instrumentation | `false` |\n| `IA_USER_AGENT` | Custom User-Agent for IA API requests | `internet-archive-mcp-server/{version} (github.com/cyanheads/internet-archive-mcp-server)` |\n| `IA_REQUEST_TIMEOUT_MS` | HTTP request timeout in milliseconds | `30000` |\n| `IA_MAX_SNAPSHOT_CHARS` | Default character cap for `ia_get_text` responses | `50000` |\n\nSee [`.env.example`](./.env.example) for the full list of optional overrides.\n\n## Running the server\n\n### Local development\n\n- **Build and run:**\n\n ```sh\n # One-time build\n bun run rebuild\n\n # Run the built server\n bun run start:stdio\n # or\n bun run start:http\n ```\n\n- **Run checks and tests:**\n\n ```sh\n bun run devcheck # Lint, format, typecheck, security\n bun run test # Vitest test suite\n bun run lint:mcp # Validate MCP definitions against spec\n ```\n\n### Docker\n\n```sh\ndocker build -t internet-archive-mcp-server .\ndocker run --rm -p 3010:3010 internet-archive-mcp-server\n```\n\nThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to `/var/log/internet-archive-mcp-server`. OpenTelemetry peer dependencies are installed by default — build with `--build-arg OTEL_ENABLED=false` to omit them.\n\n## Project structure\n\n| Directory | Purpose |\n|:----------|:--------|\n| `src/index.ts` | `createApp()` entry point — registers tools, resource, and inits services. |\n| `src/config` | Server-specific environment variable parsing and validation with Zod. |\n| `src/mcp-server/tools` | Tool definitions (`*.tool.ts`). Five tools across Wayback and IA library. |\n| `src/mcp-server/resources` | Resource definitions. `ia://item/{identifier}` item metadata resource. |\n| `src/services/wayback` | `WaybackService` — Availability API + CDX API client. |\n| `src/services/archive-search` | `ArchiveSearchService` — Solr Advanced Search client. |\n| `src/services/archive-metadata` | `ArchiveMetadataService` — Metadata API + file download client. |\n| `tests/` | Unit and integration tests mirroring `src/`. |\n\n## Development guide\n\nSee [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:\n\n- Handlers throw, framework catches — no `try/catch` in tool logic\n- Use `ctx.log` for request-scoped logging, `ctx.state` for tenant-scoped storage\n- Register new tools and resources via the barrels in `src/mcp-server/*/definitions/index.ts`\n- Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields\n\n## Contributing\n\nIssues and pull requests are welcome. Run checks and tests before submitting:\n\n```sh\nbun run devcheck\nbun run test\n```\n\n## License\n\nApache-2.0 — see [LICENSE](LICENSE) for details.\n",
"bytes": 13037,
"sha": "2a1099be061ea68f36ae3e260a92094235042eb1c2f42f108e46a709d7f5d85a",
"repo_slug": "cyanheads/internet-archive-mcp-server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_cyanheads_internet_archive_mcp_1fa9b8c6/readme"
}