internet-archive-mcp-server

---

概述

Wayback Machine 和 Internet Archive 馆藏（超过 4,000 万件）。查找并获取任意 URL 的存档快照，按关键词和元数据搜索馆藏，并检索条目元数据、文件清单和 OCR 文本。

工具

工具	描述
ia_find_snapshots	查找某个 URL 的 Wayback Machine 快照，可按最接近的时间戳查找，也可查看完整的捕获历史
ia_get_snapshot	获取指定 Wayback 时间戳对应的存档网页内容
ia_search_items	按关键词和元数据筛选条件搜索 IA 馆藏（超过 4,000 万件）
ia_get_item	检索 Archive 条目的完整元数据和文件清单
ia_get_text	检索文本条目中可读的 OCR 文本，支持分页

资源

资源	描述
ia://item/{identifier}	Archive 条目的元数据快照——标题、创建者、媒体类型、描述、主题、合集、日期、许可和文件数量

也可通过 ia_get_item 获取所有资源数据。

功能参考

ia_find_snapshots _工具

• closest 模式：通过 Availability API 返回最接近给定 timestamp 的存档；如果 Availability API 没有结果，则回退到一次 CDX 最近存档查询（优先选择 200 存档，截止时间为 25 s）
• history 模式：通过 CDX API 返回完整存档列表；按日期范围（from/to）和 HTTP 状态（status_filter）筛选
• 对于使用 timestamp:N 折叠的精确 URL，传入返回的 resume_key 和相同的 URL，即可继续查询而不跳过分页边界。游标在一小时后过期，并保留原始筛选条件；分页之间可以更改 limit。无效游标会返回 invalid_resume_key；冲突的显式筛选条件会返回 resume_key_conflict。旧版 CDX 键和通配符历史记录仍可用，但会提示分页结果可能遗漏存档
• 省略 collapse 或将其留空时，默认值为 timestamp:8（每天一条存档）；可调整为 timestamp:N，其中 N=1–14；使用 timestamp:14 时，每个不同的存档秒数列出一行
• 每次调用最多返回 10,000 条记录（limit，默认值为 100）；如果 limit 更大（最高 150,000），则每次返回 10,000 条，并在仍有存档时设置 truncated，且在 notice 中指出 resume_key；大型历史记录支持通过 resume_key 分页
• 回放 URL 始终为 https://web.archive.org/web/…
• 类型化错误：missing_timestamp（closest 模式未提供 timestamp，会在任何查询之前返回）；no_snapshots（没有匹配项）；no_snapshot_available（closest 模式下，两个来源都没有时间戳附近的存档；或者在任一模式下，Wayback Machine 不提供该 URL，例如因网站被排除而返回 403、410 或 451）；cdx_unavailable（CDX 返回 5xx、429、其他 4xx，发生超时或网络错误，响应无法读取，或 closest 模式下的 CDX 检查未完成）；availability_unavailable（closest 模式下，Availability API 返回 5xx、429、其他 4xx，发生超时或网络错误，或响应无法读取）；遇到 429、其他 4xx 或请求超时时，只会发送一次请求；429 会提示等待，4xx 会提示重复请求无济于事

---

ia_get_snapshot _工具

• 如果精确时间戳没有存档，则解析为最近的可用存档；精确的 14 位时间戳不会进行解析
• 报告 Wayback 实际提供的存档——如果请求的时间戳本身不是存档，replay_url、resolved_timestamp 和 resolved_status 会遵循 Wayback 的重定向
• 使用页面声明的字符集解码页面（依次为 Content-Type、<meta>；如果字节是有效的 UTF-8，则使用 UTF-8；否则使用 Wayback 推测的字符集或 windows-1252），然后移除脚本、样式、注释和标签，并解码字符引用，同时返回可读纯文本和回放 URL
• 最多读取页面开头的 4 MiB（页面更长时会通过 notice 提示）；输出上限为 IA_MAX_SNAPSHOT_CHARS（默认 50,000 个字符）
• 类型化错误：no_snapshot_available（时间戳附近没有存档；存档是归档错误页面——消息会指出其时间戳和归档状态；Wayback 拒绝回放并返回 4xx；或者查询返回 403、410 或 451，例如网站被排除在 Wayback Machine 之外）；content_fetch_failed（Wayback 无法访问、实施速率限制、拒绝查询，或在查询或抓取期间超时）

ia_search_items _工具

• Solr 查询语法加结构化筛选条件：mediatype、collection、creator、language 和日期范围（date_from/date_to）
• 日期边界接受 YYYY、YYYY-MM 或 YYYY-MM-DD：date_from 使用该时段的第一天，date_to 使用最后一天，并计入闰年。边界留空表示该侧不设限；日期无效时，会在发起搜索请求前返回 invalid_date_range
• mediatype 接受 Internet Archive 的 10 种媒体类型——texts、movies、audio、software、image、data、web、collection、etree、account，且不区分大小写；也会解析常见的近似值（text、book、books → texts；movie、video、videos → movies；images → image；collections → collection）
• 支持按下载量、日期、标题或随机排序（sort，采用 Solr 语法，例如 date asc 或 titleSorter asc；默认值为 downloads desc；Advanced Search 不支持按相关性排序）。排序结果相同时按 identifier 排序，确保连续翻页既不会重复也不会漏掉项目
• query 最多 2,047 个字符，这是 Advanced Search 接受的最长查询；筛选条件也计入长度，且查询中的 URL 必须加引号
• 每次调用最多返回 200 条结果（rows，默认值为 50），page 从 1 开始；在第 1 页中，如果 rows 更大（最多 10,000），则实际按 200 条返回；若仍有更多结果，会设置 truncated，并在 notice 中注明 rows: 200, page: 2
• Advanced Search 最多返回前 10,000 条结果，因此 page × rows ≤ 10,000
• 输出包含 total_found、page 和用于分页的实际 rows；空页会返回 notice，而非错误——若没有匹配项，会注明已应用的 mediatype；若 page 超出末页，则会注明末页
• title、date、creator 和 collection 可以是字符串或列表；collection 不包含各账户的 fav- 收藏列表；creator 最多列出前 10 个名称，如果某条记录还有更多名称，则会包含 creator_count
• 搜索请求发出前返回的类型化错误：invalid_date_range（日期边界无效）、invalid_mediatype（其他任何 mediatype，并列出可接受的值）、rows_over_cap（第 1 页之后的 rows 超过 200）以及 page_limit_exceeded（page × rows 超过 10,000，并注明最后可访问的页数）
• Advanced Search 返回的类型化错误：invalid_query（查询语法被拒绝、URL 未加引号、查询及其筛选条件总长度超过 2,047 个字符，或排序字段无效；会转达其错误消息）和 search_unavailable（请求失败、被限流、收到无法读取的响应、超时或无法连接）；5xx 或网络错误会重试，而 429、其他 4xx、超时或错误响应正文会在一次请求后返回；对于 4xx，还会提示重复请求无济于事

---

ia_get_item _工具

• 如果上游元数据中存在这些字段，则返回 title、creator、description、subject、collection、licenseurl、rights 和 language；creator、description、subject、collection 和 language 可以是字符串或列表
• files[] 是清单中的一页文件，顺序与上游一致；每个文件包含 format、size、md5 和直接下载链接 download_url；file_count 始终表示完整清单的文件总数
• max_files（默认值为 50，每次调用最多 500）和 file_offset（默认值为 0）用于翻阅大型项目；如果 max_files 更大（最多 300,000），则实际按 500 返回。若仍有文件，会设置 truncated 并注明下一个 file_offset
• 在分页前，format 会筛选出一种文件类型（完全匹配、不区分大小写，例如 DjVuTXT、Text PDF、VBR MP3），并将匹配数量作为 totalCount 返回；如果该格式没有匹配项，则返回空页，并通过提示列出该项目包含的格式
• 类型化错误：item_not_found（标识符未知或不可访问）、archive_unavailable（Metadata API 失败、被限流或拒绝请求、超时、无法连接或返回无法读取的响应）；首次超时会重试一次，因此一次调用最多等待两次请求超时

---

ia_get_text _工具

• max_chars 和 char_offset 用于分页读取长文档；has_more 表示仍有更多文本。max_chars 默认为 IA_MAX_SNAPSHOT_CHARS，且上限为该值——如果指定更大的值，将按该上限提供内容，并附带 notice，输出中的 max_chars 会报告实际应用的值
• 读取连续页面时，将 next_continuation 作为 continuation 传回，并使用相同的 identifier，同时省略 char_offset。游标一小时后过期，会绑定到选定的文本文件，并从其字节检查点继续读取。如果无法使用稳定的文件验证器或游标存储，响应会提供偏移量续读提示
• 续读错误：同时提供令牌和偏移量时返回 ambiguous_pagination；游标无效或文件已更改时返回 invalid_continuation；下载无法从保存的范围继续时返回 range_unavailable。恢复提示会指出应使用的 char_offset
• 上游读取会在当前页面末尾停止，因此每次调用的内存用量受页面大小限制
• 定位最佳可用文本文件——优先使用 DjVuTXT，否则回退到纯文本；source_file 表示获取的文件，source_file_bytes 表示其字节大小，信息来自条目清单
• 类型化错误：item_not_found、no_text_file、download_forbidden（受限集合）、archive_unavailable（Metadata API 或文本下载失败、遭遇速率限制或请求被拒绝、超时或无法访问）；元数据请求和下载各会在首次超时后重试一次，若再次超时则停止

---

ia://item/{identifier} _资源

• 返回 application/json——包含 title、creator、mediatype、description、subject、collection、date、licenseurl、rights、language 和 file_count
• identifier 来自 ia_search_items 结果
• 类型化错误：未知标识符返回 item_not_found；Metadata API 失败时返回 archive_unavailable

功能

基于 @cyanheads/mcp-ts-core 构建：支持 stdio 和 Streamable HTTP 传输、可插拔身份验证（none / jwt / oauth）、可替换存储（in-memory、filesystem、Supabase、Cloudflare KV/R2/D1），以及支持可选 OpenTelemetry 跟踪的结构化日志记录。

Internet Archive 专属功能：

• 无需凭据——四个 API 均为公开 API
• 三个服务层：WaybackService（Availability + CDX）、ArchiveSearchService（Solr）、ArchiveMetadataService（Metadata + 下载）
• CDX 默认按天折叠，并可配置 limit，让高捕获量 URL 的响应保持精简
• 按 IA 使用条款要求，在每个请求中通过自定义 User-Agent 标识；可通过 IA_USER_AGENT 配置

面向 Agent 的输出：

• 每个列表响应都包含分页上下文——total_found、page、rows（搜索）、resume_key（CDX 历史记录），以及 file_count 和下一个 file_offset（条目文件），使 Agent 无需猜测结果是否完整
• 类型化错误原因附带恢复提示，调用方可据此重试、修正筛选条件，或恢复已过期的续读，而无需解析错误消息
• 结构化文件清单——ia_get_item 返回文件级元数据（格式、大小、URL）和 format 筛选条件，使 Agent 无需翻阅缩略图即可选取合适的文件

开始使用

公共托管实例

可通过 https://internet-archive.caseyjhand.com/mcp 使用公共实例——无需安装。该实例提供 Streamable HTTP；每个客户端的配置格式各不相同。

适用于 Claude Code：

claude mcp add --transport http internet-archive-mcp-server https://internet-archive.caseyjhand.com/mcp

适用于 Cline（cline_mcp_settings.json）：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "streamableHttp",
      "url": "https://internet-archive.caseyjhand.com/mcp"
    }
  }
}

适用于 Cursor（mcp.json）：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "url": "https://internet-archive.caseyjhand.com/mcp"
    }
  }
}

在 Claude Desktop 中，可通过“设置”→“连接器”添加远程服务。

自托管 / 本地

无需 API 密钥——Internet Archive 的 API 完全公开。

将以下内容添加到 MCP 客户端配置文件中：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/internet-archive-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可使用 npx（无需 Bun）：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/internet-archive-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

也可使用 Docker：

{
  "mcpServers": {
    "internet-archive-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "ghcr.io/cyanheads/internet-archive-mcp-server:latest"
      ]
    }
  }
}

要使用 Streamable HTTP，请设置传输方式并启动服务：

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

前提条件

• Bun v1.4.0 或更高版本（或 Node.js v24+）。
• 无需外部账户或 API 密钥。

安装

1. 克隆仓库：

git clone https://github.com/cyanheads/internet-archive-mcp-server.git

2. 进入目录：

cd internet-archive-mcp-server

3. 安装依赖：

bun install

4. 配置环境：

cp .env.example .env
# Optional: edit .env for custom User-Agent, timeouts, etc.

配置

所有配置都会在启动时通过 src/config/server-config.ts 中的 Zod 模式进行验证。

变量	描述	默认值
MCP_TRANSPORT_TYPE	传输方式：stdio 或 http	stdio
MCP_HTTP_PORT	HTTP 服务端口	3010
MCP_AUTH_MODE	身份验证模式：none、jwt 或 oauth	none
MCP_LOG_LEVEL	日志级别（debug、info、notice、warning、error）	info
LOGS_DIR	日志文件目录（仅限 Node.js）	<project-root>/logs
STORAGE_PROVIDER_TYPE	存储后端	in-memory
OTEL_ENABLED	启用 OpenTelemetry 插桩	false
IA_USER_AGENT	IA API 请求使用的自定义 User-Agent	internet-archive-mcp-server/{version} (github.com/cyanheads/internet-archive-mcp-server)
IA_REQUEST_TIMEOUT_MS	HTTP 请求超时时间（毫秒），适用于请求头和请求体。必须为正整数，否则启动失败	30000
IA_MAX_SNAPSHOT_CHARS	每个 ia_get_text 页面默认和最大字符数（超过该值的 max_chars 将按此值提供）；同时限制 ia_get_snapshot 文本长度。必须为正整数，否则启动失败	50000

完整的可选覆盖项列表请参阅 .env.example。

运行服务

本地开发

• 构建并运行：

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• 运行检查和测试：

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t internet-archive-mcp-server .
docker run --rm -p 3010:3010 internet-archive-mcp-server

Dockerfile 默认使用 HTTP 传输、无状态会话模式，并将日志写入 /var/log/internet-archive-mcp-server。默认会安装 OpenTelemetry 对等依赖；构建时使用 --build-arg OTEL_ENABLED=false 可省略这些依赖。

项目结构

目录	用途
src/index.ts	createApp() 入口 — 注册工具和资源，并初始化服务。
src/config	使用 Zod 解析并验证服务专用环境变量。
src/mcp-server/tools	工具定义（*.tool.ts）。Wayback 和 IA 图书馆共包含五个工具。
src/mcp-server/resources	资源定义。ia://item/{identifier} 条目元数据资源。
src/services/wayback	WaybackService — Availability API 和 CDX API 客户端，以及存档页面字符集解码和文本提取。
src/services/archive-search	ArchiveSearchService — Solr Advanced Search 客户端。
src/services/archive-metadata	ArchiveMetadataService — Metadata API 和文件下载客户端。
tests/	与 src/ 目录结构对应的单元测试和集成测试。

开发指南

开发指南和架构规则请参阅 CLAUDE.md。简而言之：

• 处理程序抛出错误，由框架捕获 — 工具逻辑中不要使用 try/catch
• 使用 ctx.log 进行请求级日志记录，使用 ctx.state 管理租户级存储
• 通过 src/mcp-server/*/definitions/index.ts 中的聚合导出注册新工具和资源
• 封装外部 API 调用：验证原始数据 → 规范化为领域类型 → 返回输出模式；绝不伪造缺失字段

贡献

欢迎提交问题。提交前请运行检查和测试：

bun run devcheck
bun run test

许可证

Apache-2.0 — 详情请参阅 LICENSE。