annas-mcp
An MCP server and command-line tool for searching Anna's Archive for books and papers and downloading the file you pick. Use annas-cli in your terminal or connect annas-mcp to Claude, Cursor, Codex and other AI clients.
A paid Anna's Archive membership is required.
| Anna's Archive membership | Search through the MCP | Download by file hash or book-page URL |
|---|---|---|
| No paid membership | ❌ | ❌ |
| Brilliant Bookworm (cheapest tier) | ❌ | ✅ |
| Lucky Librarian or higher (recommended) | ✅ | ✅ |
We recommend Lucky Librarian or higher so the AI can both search and download for you. With the basic tier you'll need to manually paste each book download URL.
Disclaimer: I'm not affiliated with Anna's Archive. They were forced to introduce strict anti-scraping limits in 2026 due to massive DDoS attacks, with only paying members exempt.
MCP setup · CLI setup · Go SDK
It signs in with your membership's secret key and renews the session by itself, so you never copy cookies from a browser. If you're coming from iosifache/annas-mcp, switching is a one-line change.
| Tool | What it does |
|---|---|
book_search | Finds books, textbooks, manuals and standards by title, author or topic, filtered by format, language, source or year; can include file activity counts |
article_search | Finds journal articles by keyword, author or year, or looks one up by DOI; can include file activity counts |
metadata_search | Searches library catalogs such as Open Library, WorldCat and ISBNdb for editions and ISBNs |
book_details | Shows a result's ISBNs and other identifiers, edition, description and reported file problems |
account_status | Shows your membership and how many fast downloads are left |
book_download | Downloads a book using a file hash or Anna's Archive book-page URL |
article_download | Downloads an article by DOI or hash |
Use it only for material you are entitled to obtain, under the laws and terms that apply to you.
Go SDK
Go applications can import github.com/SokolskyNikita/annas-mcp/anna for the same search, metadata, account and verified-download operations. See the SDK guide and examples for explicit configuration, errors, timeouts and concurrency. The SDK and applications share this module’s release tags. Requires Go 1.26 or newer; install with go get github.com/SokolskyNikita/annas-mcp/anna@v0.7.0.
Setup
You need Node.js 18 or newer and an active paid Anna's Archive membership. Lucky Librarian or higher is recommended so both search and downloads work.
Get your secret key
Copy the secret key you log in with from your Anna's Archive account page. It is also your API key (API FAQ).
MCP setup
After getting your secret key, add the server to your client:
Claude Code
claude mcp add annas-mcp \
--env ANNAS_SECRET_KEY=your-secret-key \
-- npx -y annas-mcp
On native Windows (not WSL), end the command with -- cmd /c npx -y annas-mcp.
Claude Desktop, one click
Download annas-mcp.mcpb and open it, or drag it onto Settings → Extensions. Claude Desktop asks for your secret key and lets you pick a different download folder.
Claude Desktop or Cursor, by hand
Add this to Claude Desktop's config (Settings → Developer → Edit Config) or to Cursor's ~/.cursor/mcp.json:
{
"mcpServers": {
"annas-mcp": {
"command": "npx",
"args": ["-y", "annas-mcp"],
"env": {
"ANNAS_SECRET_KEY": "your-secret-key"
}
}
}
}
Codex
Add this to ~/.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 asks for your secret key, which it keeps in the system keychain, then for two optional settings; press Enter to skip them. Change them later with gemini extensions config annas-mcp.
Docker
Build the image straight from this repository:
docker build -t annas-mcp https://github.com/SokolskyNikita/annas-mcp.git
Then have your client run it, mounting your download folder at /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" }
}
}
}
On Linux, add "--user", "1000:1000" with your own user and group IDs before "annas-mcp", so the container can write to the folder.
Try it
Restart your client and ask something like "Find the EPUB of Pride and Prejudice and download it." The AI searches, picks a copy and tells you where it saved the file: annas-archive in your home folder unless you chose another.
CLI setup
Install both commands with one package:
npm install -g annas-mcp
export ANNAS_SECRET_KEY="your-secret-key"
annas-cli --help
annas-cli book-search "pride and prejudice" --format epub
Both commands support the same operations. With no arguments, annas-cli shows help and annas-mcp starts MCP. See Configuration for settings and Command line for all commands.
Or run without installing globally:
npx -y --package=annas-mcp annas-cli book-search "pride and prejudice" --format epub
Switching from iosifache/annas-mcp
This server keeps the same four tools, adds three more and reads the same ANNAS_SECRET_KEY, ANNAS_DOWNLOAD_PATH and ANNAS_BASE_URL variables. In your client's config, replace the path to the old binary with npx:
- "command": "/path/to/annas-mcp",
- "args": ["mcp"],
+ "command": "npx",
+ "args": ["-y", "annas-mcp"],
What changes:
- Searches run as your signed-in member account, so they aren't turned away with
403by the archive's browser check. Searching needs Lucky Librarian or higher. - The server picks a working official mirror by itself. Set
ANNAS_AUTO_BASE_URL=falseto use onlyANNAS_BASE_URL. - Downloads are checked against the archive's MD5 hash.
npxpicks up new releases without a manual download.
Signing in
Anna's Archive only lets signed-in members search. The server signs in with your secret key before its first request and again whenever the archive ends the session, about once a week. The session is saved between runs.
If signing in fails, the error says what each mirror answered and how to give the server a browser session instead:
- Sign in to Anna's Archive in your browser, open its developer tools and go to Application (Chrome, Edge) or Storage (Firefox, Safari) → Cookies.
- Copy the value of
aa_account_id2intoANNAS_ACCOUNT_COOKIEand restart the MCP server from your client.
The server uses that cookie until it expires, then signs in with the secret key again. Keep the secret key and cookie private.
Configuration
| Variable | Needed for | Description |
|---|---|---|
ANNAS_SECRET_KEY | Everything | Your Anna's Archive secret key. The server signs in with it and uses it for downloads. |
ANNAS_DOWNLOAD_PATH | Optional | Folder for downloaded files. Defaults to annas-archive in your home folder. See Choosing the download folder. |
ANNAS_ACCOUNT_COOKIE | Optional | An aa_account_id2 cookie to use before signing in. See Signing in. |
ANNAS_BASE_URL | Optional | Mirror to try first; the official mirrors stand in for it while it fails. Defaults to annas-archive.gl. Language versions such as es.annas-archive.gl are refused, since the server reads the archive in English. |
ANNAS_AUTO_BASE_URL | Optional | Set to false to always use ANNAS_BASE_URL instead of picking a mirror automatically. |
ANNAS_MCP_CACHE_DIR | Optional | Where the server saves its session and npx caches release binaries. See The cache folder. |
The server and CLI also read a .env file from their working directory. Variables already set in the environment take precedence.
The server only uses ANNAS_BASE_URL and the official mirrors annas-archive.gl, .pk and .gd; Choosing a mirror explains how it picks one. Whatever host you set in ANNAS_BASE_URL receives your credentials, so only use one you trust.
Choosing the download folder
Downloads go to ~/annas-archive (%USERPROFILE%\annas-archive on Windows), which is created on the first download. Set ANNAS_DOWNLOAD_PATH to use another folder. It must be an absolute path, except that a leading ~ stands for your home folder.
On macOS, Desktop, Documents, Downloads and iCloud Drive are protected: the first download there makes macOS ask whether your MCP client may access the folder. If that access is denied, downloads fail with [CONFIG] cannot write to the download folder; allow your client in System Settings → Privacy & Security → Files and Folders, or pick a folder directly in your home folder. Avoid /tmp, which the operating system clears.
Tools
The AI fills in each tool's options from your request. HOW-IT-WORKS.md lists them and what each tool returns, and --help shows them on the command line.
Before downloading, the server checks completed regular files directly in your download folder against the full MD5 hash. If one matches, it returns that file's path and size regardless of its name or extension, without downloading it or making a fresh account request; downloads_left is omitted. For article downloads by DOI, the DOI is resolved to a hash first. If no local file matches, the server downloads a verified copy and chooses a unique filename without overwriting an existing file. A fast download may use your membership's allowance, which Anna's Archive counts over a rolling 18- or 24-hour window. Downloading a file again within that window is free, and account_status shows how many are left.
Troubleshooting
Errors start with a code:
| Code | What to do |
|---|---|
[CONFIG] | A variable is missing or invalid, Anna's Archive rejected the secret key or the download folder can't be written to. Check Configuration. |
[UPSTREAM_BLOCKED] | The archive refused access. Check that your membership allows searching. If the error says no fast downloads are left, wait for the window to roll over; account_status shows the allowance. If signing in itself failed, see Signing in. |
[NOT_FOUND] | Nothing matched, or that copy has no fast download. Try another query, or another copy from the search results. |
[INVALID_ARGUMENT] | Fix the hash, DOI, id, filter, sort, page, limit or timeout. |
[REQUEST_TIMEOUT] | Retry, or raise timeout_seconds. |
[UPSTREAM] | The archive or a download server failed. The error says which one and why; retry later. |
A failed download lists every server it tried and why each one failed. The server only checks your credentials when you search or download, not when it starts.
If the server doesn't start at all, run npx -y annas-mcp --version in a terminal to see the error. The launcher unpacks releases with the system's tar, which macOS, most Linux distributions and Windows 10 or later include.
Command line
Every tool is also a command. Follow CLI setup, set the same variables (or put them in a .env file), then:
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
Add --include-stats to a book or article search to include per-file download, list, quality-vote, report and comment counts when available. Add --json for machine-readable output, --timeout 10m to change the timeout and --help to any command for all of its options.
Privacy
annas-mcp runs on your machine and has no telemetry. It sends your secret key (and cookie, if you set one) only to Anna's Archive, and downloads files from the servers Anna's Archive points it to. DOI lookups may contact doi.org. The npx launcher and the MCP Bundle contact GitHub to fetch and verify release binaries. Apart from downloaded files, it stores only the release binary, the saved session and recent mirror health, all in the cache folder. Questions: open an issue.
Contributing
See CONTRIBUTING.md for building from source, tests and releases.
Credits
The idea for this project comes from iosifache/annas-mcp, which first exposed Anna's Archive as an MCP server. This repository is a complete rewrite and shares no code with it.