Anna's Archive

annas-mcp

用于搜索 Anna's Archive 中书籍和论文并下载所选文件的 MCP 服务和命令行工具。可在终端中使用 annas-cli，或将 annas-mcp 连接到 Claude、Cursor、Codex 和其他 AI 客户端。

需要付费的 Anna's Archive 会员资格。

Anna's Archive 会员资格	通过 MCP 搜索	通过文件哈希或书籍页面 URL 下载
无付费会员资格	❌	❌
Brilliant Bookworm（最便宜的档位）	❌	✅
Lucky Librarian 或更高档位（推荐）	✅	✅

我们建议选择 Lucky Librarian 或更高档位，这样 AI 就能为你搜索和下载。 使用基础档位时，你需要手动粘贴每个书籍的下载 URL。

免责声明：我与 Anna's Archive 没有关联。由于遭受了大规模 DDoS 攻击，该网站在 2026 年被迫引入严格的反爬取限制，只有付费会员不受限制。

MCP 设置 · CLI 设置 · Go SDK

它会使用你的会员密钥登录并自动续期会话，因此你无需从浏览器复制 Cookie。如果你之前使用的是 iosifache/annas-mcp，切换只需更改一行。

工具	功能
book_search	按书名、作者或主题查找书籍、教科书、手册和标准，并按格式、语言、来源或年份筛选；可包含文件活动计数
article_search	按关键词、作者或年份查找期刊文章，或通过 DOI 查找文章；可包含文件活动计数
metadata_search	搜索 Open Library、WorldCat 和 ISBNdb 等图书馆目录，查找版本和 ISBN
book_details	显示搜索结果的 ISBN 和其他标识符、版本、描述以及报告的文件问题
account_status	显示你的会员资格以及剩余快速下载次数
book_download	使用文件哈希或 Anna's Archive 书籍页面 URL 下载书籍
article_download	通过 DOI 或哈希下载文章

仅将其用于你有权获取的材料，并遵守适用于你的法律和条款。

Go SDK

Go 应用可以导入 github.com/SokolskyNikita/annas-mcp/anna，以执行相同的搜索、元数据、账户和已验证下载操作。有关明确配置、错误、超时和并发的说明，请参阅 SDK 指南和示例。SDK 和应用共享此模块的发布标签。需要 Go 1.26 或更高版本；使用 go get github.com/SokolskyNikita/annas-mcp/[email protected] 安装。

设置

你需要 Node.js 18 或更高版本，以及有效的 Anna's Archive 付费会员资格。建议选择 Lucky Librarian 或更高档位，以便使用搜索和下载功能。

获取密钥

从 Anna's Archive 账户页面复制用于登录的密钥。它也是你的 API 密钥（API 常见问题）。

MCP 设置

获取密钥后，将服务添加到你的客户端：

Claude Code

claude mcp add annas-mcp \
  --env ANNAS_SECRET_KEY=your-secret-key \
  -- npx -y annas-mcp

在原生 Windows 上（非 WSL），请在命令末尾加上 -- cmd /c npx -y annas-mcp。

Claude Desktop，一键安装

下载 annas-mcp.mcpb 并打开，或将它拖到“设置” →“扩展程序”。Claude Desktop 会要求你输入密钥，并让你选择其他下载文件夹。

Claude Desktop 或 Cursor，手动配置

将以下内容添加到 Claude Desktop 的配置文件（“设置” →“开发者” →“编辑配置”）或 Cursor 的 ~/.cursor/mcp.json 中：

{
  "mcpServers": {
    "annas-mcp": {
      "command": "npx",
      "args": ["-y", "annas-mcp"],
      "env": {
        "ANNAS_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Codex

将以下内容添加到 ~/.codex/config.toml 中：

[mcp_servers.annas-mcp]
command = "npx"
args = ["-y", "annas-mcp"]

[mcp_servers.annas-mcp.env]
ANNAS_SECRET_KEY = "your-secret-key"

Gemini CLI

gemini extensions install https://github.com/SokolskyNikita/annas-mcp

Gemini CLI 会要求你输入密钥，并将其保存在系统钥匙串中；随后会询问两个可选设置，按 Enter 键跳过即可。之后可通过 gemini extensions config annas-mcp 更改这些设置。

Docker

直接从此仓库构建镜像：

docker build -t annas-mcp https://github.com/SokolskyNikita/annas-mcp.git

然后让客户端运行该镜像，并将你的下载文件夹挂载到 /downloads：

{
  "mcpServers": {
    "annas-mcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "ANNAS_SECRET_KEY", "-v", "/absolute/path/to/downloads:/downloads", "annas-mcp"],
      "env": { "ANNAS_SECRET_KEY": "your-secret-key" }
    }
  }
}

在 Linux 上，请在 "annas-mcp" 前添加 "--user", "1000:1000"，并将其替换为你自己的用户和组 ID，以便容器可以写入该文件夹。

试用

重启客户端，然后询问类似 “查找《傲慢与偏见》的 EPUB 并下载。” 的问题。AI 会搜索并选择一个副本，告诉你文件的保存位置：默认保存在主文件夹中的 annas-archive，除非你选择了其他文件夹。

CLI 配置

使用一个软件包安装这两个命令：

npm install -g annas-mcp
export ANNAS_SECRET_KEY="your-secret-key"

annas-cli --help
annas-cli book-search "pride and prejudice" --format epub

这两个命令支持相同的操作。不带参数运行时，annas-cli 会显示帮助信息，而 annas-mcp 会启动 MCP。设置请参阅配置，所有命令请参阅命令行。

或者，无需全局安装即可运行：

npx -y --package=annas-mcp annas-cli book-search "pride and prejudice" --format epub

从 iosifache/annas-mcp 迁移

此服务保留了原有的四个工具，新增三个工具，并读取相同的 ANNAS_SECRET_KEY、ANNAS_DOWNLOAD_PATH 和 ANNAS_BASE_URL 环境变量。在客户端配置中，将旧二进制文件的路径替换为 npx：

-      "command": "/path/to/annas-mcp",
-      "args": ["mcp"],
+      "command": "npx",
+      "args": ["-y", "annas-mcp"],

变更内容：

• 搜索会以你已登录的会员账号进行，因此不会被档案的浏览器检查以 403 拒绝。搜索需要 Lucky Librarian 或更高级别的会员资格。
• 服务会自动选择可用的官方镜像。设置 ANNAS_AUTO_BASE_URL=false 后，仅使用 ANNAS_BASE_URL。
• 下载文件会与档案提供的 MD5 哈希值进行校验。
• npx 会自动获取新版本，无需手动下载。

登录

Anna's Archive 仅允许已登录的会员进行搜索。服务会在首次请求前使用你的密钥登录；之后每当档案结束会话时也会重新登录，大约每周一次。会话会在运行期间保存。

如果登录失败，错误信息会说明每个镜像的响应，以及如何为服务提供浏览器会话：

1. 在浏览器中登录 Anna's Archive，打开开发者工具，然后前往“应用程序”（Chrome、Edge）或“存储”（Firefox、Safari）→“Cookie”。
2. 将 aa_account_id2 的值复制到 ANNAS_ACCOUNT_COOKIE，然后从客户端重启 MCP 服务。

服务会使用该 Cookie，直到它过期；之后会再次使用密钥登录。请妥善保管密钥和 Cookie。

配置

变量	用途	描述
ANNAS_SECRET_KEY	所有功能	你的 Anna's Archive 密钥。服务会使用此密钥登录并下载文件。
ANNAS_DOWNLOAD_PATH	可选	下载文件的文件夹。默认为主文件夹中的 annas-archive。请参阅选择下载文件夹。
ANNAS_ACCOUNT_COOKIE	可选	登录前使用的 aa_account_id2 Cookie。请参阅登录。
ANNAS_BASE_URL	可选	优先尝试的镜像；若其不可用，则改用官方镜像。默认为 annas-archive.gl。由于服务以英文读取档案，因此不接受 es.annas-archive.gl 之类的语言版本。
ANNAS_AUTO_BASE_URL	可选	设置为 false，即可始终使用 ANNAS_BASE_URL，而不自动选择镜像。
ANNAS_MCP_CACHE_DIR	可选	服务保存会话以及 npx 缓存发布版二进制文件的位置。请参阅缓存文件夹。

服务和 CLI 也会读取工作目录中的 .env 文件。环境中已设置的变量优先级更高。

服务只使用 ANNAS_BASE_URL 和官方镜像 annas-archive.gl、.pk 与 .gd；选择镜像说明了它如何选择镜像。你在 ANNAS_BASE_URL 中设置的主机都会收到你的凭据，因此请仅使用你信任的主机。

选择下载文件夹

文件会下载到 ~/annas-archive（Windows 上为 %USERPROFILE%\annas-archive），该文件夹会在首次下载时创建。设置 ANNAS_DOWNLOAD_PATH 可改用其他文件夹。路径必须是绝对路径，但开头的 ~ 可代表你的主文件夹。

在 macOS 上，桌面、文稿、下载和 iCloud Drive 受保护：首次向这些位置下载时，macOS 会询问是否允许你的 MCP 客户端访问该文件夹。如果拒绝访问，下载会失败并提示 [CONFIG] cannot write to the download folder；请在“系统设置” →“隐私与安全性” →“文件与文件夹”中允许你的客户端访问，或选择主文件夹中的其他位置。请避免使用 /tmp，因为操作系统会清除其中的内容。

工具

AI 会根据你的请求填写每个工具的选项。HOW-IT-WORKS.md列出了这些选项及各工具的返回内容，--help 则会在命令行中显示这些内容。

下载前，服务会检查下载文件夹中的已完成普通文件，并与完整 MD5 哈希值进行比对。如果有文件匹配，服务会返回该文件的路径和大小，无论其名称或扩展名为何；此时不会下载文件或重新请求账户信息，也不会返回 downloads_left。通过 DOI 下载文章时，会先将 DOI 解析为哈希值。如果没有匹配的本地文件，服务会下载经过验证的副本，并选择一个不会覆盖现有文件的唯一文件名。快速下载可能会使用你的会员下载额度；Anna's Archive 会按滚动的 18 或 24 小时窗口统计额度。在此窗口内再次下载同一文件无需消耗额度，account_status 会显示剩余额度。

故障排查

错误以代码开头：

代码	处理方法
[CONFIG]	缺少变量或变量无效、Anna's Archive 拒绝了密钥，或无法写入下载文件夹。请检查配置。
[UPSTREAM_BLOCKED]	档案拒绝了访问。请确认你的会员资格允许搜索。如果错误提示没有剩余快速下载次数，请等待额度刷新；account_status 会显示可用额度。如果登录本身失败，请参阅登录。
[NOT_FOUND]	没有匹配结果，或者该副本不支持快速下载。请尝试其他查询，或搜索结果中的其他副本。
[INVALID_ARGUMENT]	修正哈希值、DOI、id、筛选条件、排序方式、页码、数量限制或超时时间。
[REQUEST_TIMEOUT]	重试，或调高 timeout_seconds 的值。
[UPSTREAM]	档案或下载服务出错。错误信息会说明出错的是哪个服务以及原因；请稍后重试。

下载失败时，会列出尝试过的所有服务以及每个服务失败的原因。服务仅会在你搜索或下载时检查凭据，而不是在启动时检查。

如果服务完全无法启动，请在终端运行 npx -y annas-mcp --version 查看错误信息。启动器使用系统的 tar 解压发布包；macOS、大多数 Linux 发行版以及 Windows 10 或更高版本均包含该工具。

命令行

每个工具也都可以作为命令使用。请按照 CLI 设置进行操作，设置相同的变量（或将它们放入 .env 文件），然后：

annas-cli book-search "pride and prejudice" --language en --format epub --include-stats
annas-cli book-search --author "Jane Austen" --year 1813 --sort oldest
annas-cli article-search 10.1038/nature14539
annas-cli metadata-search 9780141439518
annas-cli book-details <hash>
annas-cli account-status
annas-cli book-download <hash> "Pride and Prejudice.epub"
annas-cli article-download 10.1038/nature14539

在图书或文章搜索命令中添加 --include-stats，可在有数据时包含每个文件的下载次数、收藏次数、质量投票数、举报数和评论数。添加 --json 可输出机器可读的结果；添加 --timeout 10m 可更改超时时间；在任何命令后添加 --help 可查看该命令的所有选项。

隐私

annas-mcp 在你的计算机上运行，不会收集遥测数据。它只会将密钥（以及你设置的 Cookie）发送给 Anna's Archive，并从 Anna's Archive 指向的服务下载文件。DOI 查询可能会联系 doi.org。npx 启动器和 MCP Bundle 会联系 GitHub，以获取并验证发布二进制文件。除了下载的文件，它只会在缓存文件夹中存储发布二进制文件、已保存的会话和近期镜像健康状况。如有疑问：提交 issue。

贡献

有关从源代码构建、测试和发布的信息，请参阅 CONTRIBUTING.md。

致谢

本项目的构想来自 iosifache/annas-mcp，它最先将 Anna's Archive 接入为 MCP 服务。本仓库经过了完整重写，与其没有共享任何代码。

许可证

MIT