Anna's Archive MCP

Anna's Archive MCP: busca y descarga libros y artículos por título, autor o DOI.

Documentación

annas-mcp

Un servidor MCP que permite a Claude, Cursor, Codex y otros clientes de IA buscar en Anna's Archive libros y artículos, y descargar el archivo que elijas. También funciona como herramienta de línea de comandos.

Inicia sesión con la clave secreta de tu membresía y renueva la sesión automáticamente, para que nunca tengas que copiar cookies de un navegador. Si vienes de iosifache/annas-mcp, cambiar es un cambio de una sola línea.

Herramienta	Qué hace
`book_search`	Encuentra libros, libros de texto, manuales y normas por título, autor o tema, filtrados por formato, idioma, fuente o año; puede incluir recuentos de actividad de archivos
`article_search`	Encuentra artículos de revistas por palabra clave, autor o año, o busca uno por DOI; puede incluir recuentos de actividad de archivos
`metadata_search`	Busca en catálogos de bibliotecas como Open Library, WorldCat e ISBNdb ediciones e ISBNs
`book_details`	Muestra los ISBNs y otros identificadores de un resultado, edición, descripción y problemas de archivo reportados
`account_status`	Muestra tu membresía y cuántas descargas rápidas quedan
`book_download`	Descarga un libro usando el hash de un resultado de búsqueda
`article_download`	Descarga un artículo por DOI o hash

Úsalo solo para material al que tengas derecho a acceder, según las leyes y términos que te apliquen.

Configuración

Necesitas Node.js 18 o más reciente y una membresía de Anna's Archive. Cualquier nivel puede descargar; buscar requiere Lucky Librarian o superior.

1. Obtén tu clave secreta

Copia la clave secreta con la que inicias sesión desde tu página de cuenta de Anna's Archive. También es tu clave de API (FAQ de API).

2. Añade el servidor a tu cliente

Claude Code

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

En Windows nativo (no WSL), termina el comando con -- cmd /c npx -y annas-mcp.

Claude Desktop, con un clic

Descarga annas-mcp.mcpb y ábrelo, o arrástralo a Configuración → Extensiones. Claude Desktop te pedirá tu clave secreta y te permitirá elegir una carpeta de descarga diferente.

Claude Desktop o Cursor, manualmente

Añade esto a la configuración de Claude Desktop (Configuración → Desarrollador → Editar Configuración) o al ~/.cursor/mcp.json de Cursor:

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

Codex

Añade esto a ~/.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 te pedirá tu clave secreta, que guarda en el llavero del sistema, y luego dos configuraciones opcionales; presiona Enter para omitirlas. Cámbialas más tarde con gemini extensions config annas-mcp.

Docker

Construye la imagen directamente desde este repositorio:

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

Luego haz que tu cliente la ejecute, montando tu carpeta de descargas en /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" }
    }
  }
}

En Linux, añade "--user", "1000:1000" con tus propios IDs de usuario y grupo antes de "annas-mcp", para que el contenedor pueda escribir en la carpeta.

3. Pruébalo

Reinicia tu cliente y pide algo como "Encuentra el EPUB de Orgullo y Prejuicio y descárgalo". La IA busca, elige una copia y te dice dónde guardó el archivo: annas-archive en tu carpeta de inicio a menos que elijas otra.

Cambiar desde iosifache/annas-mcp

Este servidor mantiene las mismas cuatro herramientas, añade tres más y lee las mismas variables ANNAS_SECRET_KEY, ANNAS_DOWNLOAD_PATH y ANNAS_BASE_URL. En la configuración de tu cliente, reemplaza la ruta al binario antiguo con npx:

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

Qué cambia:

Las búsquedas se ejecutan con tu cuenta de miembro con sesión iniciada, por lo que no son rechazadas con 403 por la verificación del navegador del archivo. Buscar requiere Lucky Librarian o superior.
El servidor elige automáticamente un espejo oficial que funcione. Establece ANNAS_AUTO_BASE_URL=false para usar solo ANNAS_BASE_URL.
Las descargas se verifican contra el hash MD5 del archivo.
npx detecta nuevas versiones sin descarga manual.

Iniciar sesión

Anna's Archive solo permite buscar a miembros con sesión iniciada. El servidor inicia sesión con tu clave secreta antes de su primera solicitud y nuevamente cuando el archivo termina la sesión, aproximadamente una vez por semana. La sesión se guarda entre ejecuciones.

Si el inicio de sesión falla, el error indica qué respondió cada espejo y cómo darle al servidor una sesión de navegador en su lugar:

Inicia sesión en Anna's Archive en tu navegador, abre las herramientas de desarrollador y ve a Aplicación (Chrome, Edge) o Almacenamiento (Firefox, Safari) → Cookies.
Copia el valor de aa_account_id2 en ANNAS_ACCOUNT_COOKIE y reinicia el servidor MCP desde tu cliente.

El servidor usa esa cookie hasta que expire, luego inicia sesión nuevamente con la clave secreta. Mantén la clave secreta y la cookie privadas.

Configuración

Variable	Necesaria para	Descripción
`ANNAS_SECRET_KEY`	Todo	Tu clave secreta de Anna's Archive. El servidor inicia sesión con ella y la usa para descargas.
`ANNAS_DOWNLOAD_PATH`	Opcional	Carpeta para archivos descargados. Por defecto es `annas-archive` en tu carpeta de inicio. Ver Elegir la carpeta de descargas.
`ANNAS_ACCOUNT_COOKIE`	Opcional	Una cookie `aa_account_id2` para usar antes de iniciar sesión. Ver Iniciar sesión.
`ANNAS_BASE_URL`	Opcional	Espejo a probar primero; los espejos oficiales lo reemplazan mientras falla. Por defecto es `annas-archive.gl`. Las versiones de idioma como `es.annas-archive.gl` son rechazadas, ya que el servidor lee el archivo en inglés.
`ANNAS_AUTO_BASE_URL`	Opcional	Establece a `false` para usar siempre `ANNAS_BASE_URL` en lugar de elegir un espejo automáticamente.
`ANNAS_MCP_CACHE_DIR`	Opcional	Dónde guarda el servidor su sesión y `npx` almacena en caché los binarios de versiones. Ver La carpeta de caché.

El servidor y la CLI también leen un archivo .env desde su directorio de trabajo. Las variables ya establecidas en el entorno tienen prioridad.

El servidor solo usa ANNAS_BASE_URL y los espejos oficiales annas-archive.gl, .pk y .gd; Elegir un espejo explica cómo elige uno. Cualquier host que establezcas en ANNAS_BASE_URL recibe tus credenciales, así que solo usa uno en el que confíes.

Elegir la carpeta de descargas

Las descargas van a ~/annas-archive (%USERPROFILE%\annas-archive en Windows), que se crea en la primera descarga. Establece ANNAS_DOWNLOAD_PATH para usar otra carpeta. Debe ser una ruta absoluta, excepto que un ~ inicial representa tu carpeta de inicio.

En macOS, Escritorio, Documentos, Descargas e iCloud Drive están protegidos: la primera descarga allí hace que macOS pregunte si tu cliente MCP puede acceder a la carpeta. Si se deniega ese acceso, las descargas fallan con [CONFIG] cannot write to the download folder; permite tu cliente en Configuración del Sistema → Privacidad y Seguridad → Archivos y Carpetas, o elige una carpeta directamente en tu carpeta de inicio. Evita /tmp, que el sistema operativo limpia.

Herramientas

La IA completa las opciones de cada herramienta a partir de tu solicitud. HOW-IT-WORKS.md las enumera y qué devuelve cada herramienta, y --help las muestra en la línea de comandos.

Antes de descargar, el servidor verifica los archivos regulares completados directamente en tu carpeta de descargas contra el hash MD5 completo. Si uno coincide, devuelve la ruta y el tamaño de ese archivo independientemente de su nombre o extensión, sin descargarlo ni hacer una nueva solicitud de cuenta; downloads_left se omite. Para descargas de artículos por DOI, el DOI se resuelve a un hash primero. Si ningún archivo local coincide, el servidor descarga una copia verificada y elige un nombre de archivo único sin sobrescribir un archivo existente. Una descarga rápida puede usar el saldo de tu membresía, que Anna's Archive cuenta en una ventana móvil de 18 o 24 horas. Descargar un archivo nuevamente dentro de esa ventana es gratis, y account_status muestra cuántas quedan.

Solución de problemas

Los errores comienzan con un código:

Código	Qué hacer
`[CONFIG]`	Falta una variable o es inválida, Anna's Archive rechazó la clave secreta o la carpeta de descargas no se puede escribir. Revisa Configuración.
`[UPSTREAM_BLOCKED]`	El archivo rechazó el acceso. Verifica que tu membresía permita buscar. Si el error dice que no quedan descargas rápidas, espera a que la ventana se reinicie; `account_status` muestra el saldo. Si el inicio de sesión en sí falló, ver Iniciar sesión.
`[NOT_FOUND]`	Nada coincidió, o esa copia no tiene descarga rápida. Prueba otra consulta, u otra copia de los resultados de búsqueda.
`[INVALID_ARGUMENT]`	Corrige el hash, DOI, id, filtro, orden, página, límite o tiempo de espera.
`[REQUEST_TIMEOUT]`	Reintenta, o aumenta `timeout_seconds`.
`[UPSTREAM]`	El archivo o un servidor de descargas falló. El error indica cuál y por qué; reintenta más tarde.

Una descarga fallida enumera cada servidor que intentó y por qué falló cada uno. El servidor solo verifica tus credenciales cuando buscas o descargas, no cuando se inicia.

Si el servidor no se inicia en absoluto, ejecuta npx -y annas-mcp --version en una terminal para ver el error. El lanzador desempaqueta las versiones con el tar del sistema, que macOS, la mayoría de las distribuciones de Linux y Windows 10 o posterior incluyen.

Línea de comandos

Cada herramienta también es un comando. Establece las mismas variables (o ponlas en un archivo .env), luego:

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

Añade --include-stats a una búsqueda de libro o artículo para incluir recuentos de descarga, lista, votos de calidad, informes y comentarios por archivo cuando estén disponibles. Añade --json para salida legible por máquina, --timeout 10m para cambiar el tiempo de espera y --help a cualquier comando para todas sus opciones.

Privacidad

annas-mcp se ejecuta en tu máquina y no tiene telemetría. Envía tu clave secreta (y cookie, si la estableces) solo a Anna's Archive, y descarga archivos de los servidores a los que Anna's Archive lo dirige. Las búsquedas de DOI pueden contactar a doi.org. El lanzador npx y el MCP Bundle contactan a GitHub para obtener y verificar los binarios de versiones. Aparte de los archivos descargados, solo almacena el binario de la versión, la sesión guardada y la salud reciente de los espejos, todo en la carpeta de caché. Preguntas: abre un issue.

Contribuir

Ver CONTRIBUTING.md para compilar desde el código fuente, pruebas y versiones.

Créditos

La idea de este proyecto proviene de iosifache/annas-mcp, que primero expuso Anna's Archive como servidor MCP. Este repositorio es una reescritura completa y no comparte código con él.

Licencia

MIT