Wayback Machine MCP Server

Instructions

Implementation Reference

• wayback_mcp/server.py:68-74 (registration)

  Registers the get_snapshots tool with FastMCP using @app.tool decorator, specifying name and description.

  @app.tool(
  	name="get_snapshots",
  	description=(
  		"Get a list of available Wayback Machine snapshots for a URL. "
  		"Dates use YYYYMMDD, match_type is one of: exact, prefix, host, domain."
  	),
  )

• wayback_mcp/server.py:75-123 (handler)

  The main handler function for the get_snapshots tool. It builds CDX API parameters, fetches and parses the JSON response, processes snapshot rows into structured dicts, and returns the list of snapshots.

  async def get_snapshots(
  	url: str,
  	from_: Optional[str] = None,
  	to: Optional[str] = None,
  	limit: int = 100,
  	match_type: Literal["exact", "prefix", "host", "domain"] = "exact",
  ) -> Dict[str, Any]:
  	"""
  	List snapshots using the CDX API. Returns a structured result with a normalized list.
  	Parameter `from_` maps to `from` in the CDX API.
  	"""
  	params = _build_cdx_params(url, from_, to, limit, match_type)
  	raw = await _fetch_json(CDX_ENDPOINT, params)
  
  	if not isinstance(raw, list) or not raw:
  		return {"url": url, "snapshots": [], "count": 0}
  
  	headers = raw[0]
  	rows = raw[1:]
  
  	# Expected headers from CDX: urlkey,timestamp,original,mimetype,statuscode,digest,length
  	index_by_name = {name: idx for idx, name in enumerate(headers)}
  
  	results: List[Dict[str, Any]] = []
  	for row in rows:
  		try:
  			ts = row[index_by_name.get("timestamp", 1)]
  			orig = row[index_by_name.get("original", 2)]
  			mime = row[index_by_name.get("mimetype", 3)]
  			status = row[index_by_name.get("statuscode", 4)]
  			digest = row[index_by_name.get("digest", 5)]
  			length = row[index_by_name.get("length", 6)]
  			archived_url = f"{WAYBACK_ENDPOINT}/{ts}/{orig}"
  			results.append(
  				{
  					"timestamp": ts,
  					"original_url": orig,
  					"mimetype": mime,
  					"statuscode": status,
  					"digest": digest,
  					"length": length,
  					"archived_url": archived_url,
  				}
  			)
  		except Exception:
  			# Skip malformed rows
  			continue
  
  	return {"url": url, "snapshots": results, "count": len(results)}

• wayback_mcp/server.py:23-43 (helper)

  Helper function used by get_snapshots to construct the parameters dictionary for the CDX API query.

  def _build_cdx_params(
  	url: str,
  	from_date: Optional[str],
  	to_date: Optional[str],
  	limit: int,
  	match_type: Literal["exact", "prefix", "host", "domain"],
  ) -> Dict[str, Any]:
  	params: Dict[str, Any] = {
  		"url": url,
  		"output": "json",
  		"limit": str(limit),
  		"matchType": match_type,
  		# Clean results a bit:
  		"filter": "statuscode:200",
  		"collapse": "digest",
  	}
  	if from_date:
  		params["from"] = from_date
  	if to_date:
  		params["to"] = to_date
  	return params

• wayback_mcp/server.py:46-55 (helper)

  Helper function used by get_snapshots to fetch JSON data from the CDX API endpoint.

  async def _fetch_json(url: str, params: Dict[str, Any]) -> Any:
  	async with httpx.AsyncClient(
  		headers={"User-Agent": USER_AGENT},
  		timeout=httpx.Timeout(20.0),
  		follow_redirects=True,
  	) as client:
  		resp = await client.get(url, params=params)
  		resp.raise_for_status()
  		return resp.json()