wayback-mcp

A Model Context Protocol server giving Claude and other LLM clients structured access to the Internet Archive's Wayback Machine.

Overview

wayback-mcp is an async Python MCP server that exposes the Internet Archive's six core APIs — Availability, CDX, Advanced Search, Metadata, and Wayback content — as first-class tools, prompts, and resources for any MCP-compatible client. It handles rate limiting, retry/back-off, and response shape normalisation so the model only sees structured Pydantic data.

Features

• Six MCP tools covering availability checks, snapshot lookups, full-text item search, domain crawls, page-text extraction, and item metadata

• Four guided prompts — research_topic, track_site_changes, audit_link_rot, setup_authentication

• One MCP resource — wayback://item/{identifier} exposes IA item metadata as JSON

• Async token-bucket rate limiter with per-endpoint buckets and Retry-After honoring

• In-memory response cache with per-endpoint TTLs to keep token usage and IA load low

• Internet Archive S3 authentication (optional) for higher rate-limit ceilings

• Structured error model — expected failures return ToolError; unexpected ones raise

• Tested against live IA APIs via an opt-in --integration pytest flag

Installation

As an MCP server

Interactive installer (recommended)

uvx mcp-server-wayback --install

You'll get a numbered menu of supported clients — pick one, the installer writes the config for you, then restart that client. Run uvx mcp-server-wayback --list-clients to see the menu without launching it.

Non-interactive installers

Pass the client key explicitly (handy for scripts and dotfiles):

uvx mcp-server-wayback --install claude-desktop
uvx mcp-server-wayback --install claude-code-user        # ~/.claude.json
uvx mcp-server-wayback --install claude-code-project     # ./.mcp.json in cwd
uvx mcp-server-wayback --install cursor                  # ./.cursor/mcp.json
uvx mcp-server-wayback --install windsurf
uvx mcp-server-wayback --install zed                     # uses Zed's context_servers key
uvx mcp-server-wayback --install antigravity             # ~/.gemini/antigravity/mcp_config.json

For clients with their own MCP CLI:

claude mcp add wayback -- uvx mcp-server-wayback
codex mcp add wayback -- uvx mcp-server-wayback

To include Internet Archive API keys for higher rate limits at install time:

claude mcp add wayback \
  --env WAYBACK_MCP_IA_ACCESS_KEY=xxx \
  --env WAYBACK_MCP_IA_SECRET_KEY=xxx \
  -- uvx mcp-server-wayback

Need uvx? brew install uv on macOS, or pipx install uv. Python 3.11+ required.

Manual configuration

For clients that use a JSON config file, add this to the appropriate section:

{
  "wayback": {
    "command": "uvx",
    "args": ["mcp-server-wayback"],
    "env": {
      "WAYBACK_MCP_IA_ACCESS_KEY": "your-access-key",
      "WAYBACK_MCP_IA_SECRET_KEY": "your-secret-key"
    }
  }
}

The env block is optional — the server works anonymously without credentials. See Authentication for details.

Project-scoped (workspace) config

Claude Code supports a per-workspace .mcp.json in the repo root. Useful for testing env-var changes without touching your global config:

claude mcp add wayback --scope project -- uvx mcp-server-wayback

Open Claude Code from that folder — it picks up .mcp.json automatically. Add it to .gitignore if it contains real keys.

Uninstalling

uvx mcp-server-wayback --uninstall                  # interactive picker
uvx mcp-server-wayback --uninstall claude-desktop   # or pass a client key
claude mcp remove wayback                           # Claude Code native CLI
codex mcp remove wayback                            # Codex CLI native CLI

Quick examples

What to ask the agent once the server is wired up:

Has openai.com been archived? Show me the closest snapshot.

Find archived snapshots of nytimes.com from 2001.

What did anthropic.com look like in early 2023?

Search the Internet Archive for documentaries about the moon landing.

Walk me through how anthropic.com's homepage has changed over the past year.

I have a list of URLs from a 2015 reading list — check which are still recoverable from the Wayback Machine.

Or use a slash command for a guided workflow: /wayback:research_topic, /wayback:track_site_changes, /wayback:audit_link_rot, /wayback:setup_authentication.

Tools

check_availability

Check whether a URL has been archived and return the closest snapshot.

lookup_snapshots

List all CDX snapshots for a URL with optional date-range and HTTP-status filters.

search_archive

Search Internet Archive collections using Lucene query syntax. Returns matching items with identifier, title, mediatype, year, creator, subject, and download count.

search_domain

Discover archived URLs under a domain or path prefix. Auto-detects whether to do a wildcard-domain or prefix match from the input shape.

get_snapshot_content

Fetch an archived web page and extract its readable text. Strips the Wayback toolbar, navigation, and boilerplate so the model only sees article-quality content.

Returns {text, word_count, snapshot_url, timestamp, sparse_content_warning}.

get_item_metadata

Return rich structured metadata for any Internet Archive item by its identifier.

Returns title, description, creator, subject, mediatype, year, downloads, full file list, and more.

Prompts

Resources

Authentication

The server works anonymously by default. Configure Internet Archive S3 keys to raise your rate-limit ceiling and remove 429 errors during heavy use:

1. Visit https://archive.org/account/s3.php (free archive.org account required)

2. Copy your access key and secret key

3. Add them to the env block of your MCP config (see Manual configuration) — or run the setup_authentication prompt for an interactive walkthrough

Keys never leave your machine. They live only in your local MCP config and the server subprocess's environment.

Technical details

• Transport: stdio (MCP client integration)

• Caching: in-memory with per-endpoint TTLs

  • Metadata, snapshot content: 24 hours (immutable once captured)

  • CDX results: 1 hour (grows but never mutates)

  • Search results: 15 minutes (relevance can shift)

• Rate limiting: async token-bucket per endpoint group with automatic Retry-After handling for 429 responses

• Validation: Pydantic 2 schemas for every input and output

• Python 3.11+

Development

git clone https://github.com/lakshyamehta03/wayback-machine-mcp.git
cd wayback-machine-mcp
uv sync
uv run mcp-server-wayback      # run the server
uv run pytest                  # unit tests (httpx mocked via respx)
uv run pytest --integration    # also hit live Internet Archive APIs

CI runs the unit suite on every push and pull request via GitHub Actions.

License

MIT. The Wayback Machine logo is © Internet Archive and used here under fair use to identify the upstream service this project integrates with.

Acknowledgments

• The Internet Archive for the Wayback Machine and the open APIs that make this server possible

• Anthropic for the Model Context Protocol specification and SDK