annas

Anna's Archive MCP Server (annas) exposes search and download capabilities for books and articles from Anna's Archive. You can run the server locally and connect a preferred MCP client (e.g., Claude Desktop or another MCP client) to execute host capabilities like searching for titles, authors, or topics, and downloading content by MD5 hash or DOI. The server wraps the Anna's Archive CLI/binary interactions behind the MCP interface, enabling programmatic access to search_book, download_book, search_article, and download_article operations via the MCP tooling. Typical workflows include starting the MCP server, then issuing an MCP client request to search for a book by title or author, and subsequently downloading the selected item by its MD5 or DOI as supported by the client’s MCP command set.

The MCP server exposes the following operations through the MCP tool and CLI as documented in the project README: book_search, book-download, article_search, and article-download. The CLI example shows how a client like Claude Desktop can pass an argument set to the server, including environment variables for authentication and download paths. Ensure your environment provides the required API key and download path, and optionally a base URL if you’re using a mirrors setup. This setup enables automated retrieval of documents under permissive licensing frameworks, while urging responsible usage and compliance with copyright and licensing terms.

Prerequisites

• A compatible MCP client or environment to run MCP servers
• Node.js installed on the host (for running the MCP server wrapper in this configuration)
• Access to Anna's Archive API credentials (ANNAS_SECRET_KEY) and a download path (ANNAS_DOWNLOAD_PATH)

Step-by-step installation

1. Install Node.js if not already installed (visit https://nodejs.org to download and install).

2. Download the Anna's Archive MCP server binary or the wrapper script you intend to run locally. Ensure you have the path to the server script (for example, path/to/annas-mcp-server.js).

3. Create a working directory for the MCP server configuration and environment:

   • mkdir -p ~/annas-mcp
   • cd ~/annas-mcp

4. Place the server script (annas-mcp-server.js) in the working directory or reference its absolute path in the command configuration.

5. Prepare a .env or environment variables for authentication and download path:

   • ANNAS_SECRET_KEY=<your-annas-api-key>
   • ANNAS_DOWNLOAD_PATH=</path/where/downloads/go>
   • Optional: ANNAS_BASE_URL=https://annas-archive.li (or another mirror)

6. Start the MCP server using the mcp_config mapping (as described in the repository's instructions for your MCP client). Example (adjust paths as needed):

   node path/to/annas-mcp-server.js

7. Connect your MCP client and configure a client-side mapping for the server, matching the command, arguments, and environment variables described in the mcp_config section.

Tips and notes:

• Ensure ANNAS_SECRET_KEY and ANNAS_DOWNLOAD_PATH are correctly set to enable API access and proper download destinations.
• If you switch to a different Anna's Archive mirror, set ANNAS_BASE_URL accordingly to ensure the server points to the correct endpoint.
• If your environment uses a .env file, you can place the key-value pairs there and load them into the process before starting the server.
• Some MCP clients require specific naming conventions for operations (e.g., book_search, article-download); verify client compatibility with the annas MCP integration.
• Monitor the server logs for authentication errors or download path permissions issues, which are common obstacles in initial setups.