Anna's Archive MCP

Anna's Archive MCP: pesquise e baixe livros e artigos por título, autor ou DOI.

Documentação

annas-mcp

Um servidor MCP que permite que Claude, Cursor, Codex e outros clientes de IA pesquisem no Anna's Archive por livros e artigos e baixem o arquivo que você escolher. Ele também funciona como uma ferramenta de linha de comando.

Ele faz login com a chave secreta da sua assinatura e renova a sessão automaticamente, então você nunca precisa copiar cookies do navegador. Se você está vindo do iosifache/annas-mcp, migrar é uma mudança de uma linha.

Ferramenta	O que faz
`book_search`	Encontra livros, livros didáticos, manuais e normas por título, autor ou tópico, filtrados por formato, idioma, fonte ou ano; pode incluir contagens de atividade de arquivos
`article_search`	Encontra artigos de periódicos por palavra-chave, autor ou ano, ou busca um por DOI; pode incluir contagens de atividade de arquivos
`metadata_search`	Pesquisa catálogos de bibliotecas como Open Library, WorldCat e ISBNdb por edições e ISBNs
`book_details`	Mostra os ISBNs e outros identificadores de um resultado, edição, descrição e problemas relatados no arquivo
`account_status`	Mostra sua assinatura e quantos downloads rápidos restam
`book_download`	Baixa um livro usando o hash de um resultado de pesquisa
`article_download`	Baixa um artigo por DOI ou hash

Use apenas para material ao qual você tem direito de acesso, de acordo com as leis e termos que se aplicam a você.

Configuração

Você precisa do Node.js 18 ou mais recente e de uma assinatura do Anna's Archive. Qualquer nível pode baixar; pesquisar exige Lucky Librarian ou superior.

1. Obtenha sua chave secreta

Copie a chave secreta com a qual você faz login na sua página de conta do Anna's Archive. Ela também é sua chave de API (FAQ da API).

2. Adicione o servidor ao seu cliente

Claude Code

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

No Windows nativo (não WSL), termine o comando com -- cmd /c npx -y annas-mcp.

Claude Desktop, com um clique

Baixe annas-mcp.mcpb e abra-o, ou arraste-o para Configurações → Extensões. O Claude Desktop pede sua chave secreta e permite escolher uma pasta de download diferente.

Claude Desktop ou Cursor, manualmente

Adicione isto à configuração do Claude Desktop (Configurações → Desenvolvedor → Editar Configuração) ou ao ~/.cursor/mcp.json do Cursor:

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

Codex

Adicione isto ao ~/.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

O Gemini CLI pede sua chave secreta, que ele guarda no chaveiro do sistema, e depois duas configurações opcionais; pressione Enter para ignorá-las. Altere-as depois com gemini extensions config annas-mcp.

Docker

Construa a imagem diretamente deste repositório:

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

Depois, faça seu cliente executá-la, montando sua pasta de download em /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" }
    }
  }
}

No Linux, adicione "--user", "1000:1000" com seus próprios IDs de usuário e grupo antes de "annas-mcp", para que o contêiner possa gravar na pasta.

3. Experimente

Reinicie seu cliente e peça algo como "Encontre o EPUB de Orgulho e Preconceito e baixe-o." A IA pesquisa, escolhe uma cópia e informa onde salvou o arquivo: annas-archive na sua pasta pessoal, a menos que você escolha outra.

Migrando do iosifache/annas-mcp

Este servidor mantém as mesmas quatro ferramentas, adiciona três outras e lê as mesmas variáveis ANNAS_SECRET_KEY, ANNAS_DOWNLOAD_PATH e ANNAS_BASE_URL. Na configuração do seu cliente, substitua o caminho para o binário antigo por npx:

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

O que muda:

As pesquisas são executadas como sua conta de membro conectada, então não são recusadas com 403 pela verificação de navegador do arquivo. Pesquisar exige Lucky Librarian ou superior.
O servidor escolhe um espelho oficial funcional automaticamente. Defina ANNAS_AUTO_BASE_URL=false para usar apenas ANNAS_BASE_URL.
Os downloads são verificados contra o hash MD5 do arquivo.
npx detecta novos lançamentos sem download manual.

Entrando

O Anna's Archive só permite que membros conectados pesquisem. O servidor faz login com sua chave secreta antes da primeira solicitação e novamente sempre que o arquivo encerra a sessão, cerca de uma vez por semana. A sessão é salva entre execuções.

Se o login falhar, o erro informa o que cada espelho respondeu e como fornecer uma sessão de navegador ao servidor:

Entre no Anna's Archive no seu navegador, abra as ferramentas do desenvolvedor e vá para Aplicativo (Chrome, Edge) ou Armazenamento (Firefox, Safari) → Cookies.
Copie o valor de aa_account_id2 para ANNAS_ACCOUNT_COOKIE e reinicie o servidor MCP pelo seu cliente.

O servidor usa esse cookie até expirar e depois faz login novamente com a chave secreta. Mantenha a chave secreta e o cookie privados.

Configuração

Variável	Necessária para	Descrição
`ANNAS_SECRET_KEY`	Tudo	Sua chave secreta do Anna's Archive. O servidor faz login com ela e a usa para downloads.
`ANNAS_DOWNLOAD_PATH`	Opcional	Pasta para arquivos baixados. O padrão é `annas-archive` na sua pasta pessoal. Veja Escolhendo a pasta de download.
`ANNAS_ACCOUNT_COOKIE`	Opcional	Um cookie `aa_account_id2` para usar antes do login. Veja Entrando.
`ANNAS_BASE_URL`	Opcional	Espelho para tentar primeiro; os espelhos oficiais o substituem enquanto ele falha. O padrão é `annas-archive.gl`. Versões de idioma como `es.annas-archive.gl` são recusadas, pois o servidor lê o arquivo em inglês.
`ANNAS_AUTO_BASE_URL`	Opcional	Defina como `false` para sempre usar `ANNAS_BASE_URL` em vez de escolher um espelho automaticamente.
`ANNAS_MCP_CACHE_DIR`	Opcional	Onde o servidor salva sua sessão e `npx` armazena em cache os binários de lançamento. Veja A pasta de cache.

O servidor e a CLI também leem um arquivo .env do diretório de trabalho. Variáveis já definidas no ambiente têm precedência.

O servidor usa apenas ANNAS_BASE_URL e os espelhos oficiais annas-archive.gl, .pk e .gd; Escolhendo um espelho explica como ele escolhe um. Qualquer host que você definir em ANNAS_BASE_URL recebe suas credenciais, então use apenas um em que confie.

Escolhendo a pasta de download

Os downloads vão para ~/annas-archive (%USERPROFILE%\annas-archive no Windows), que é criada no primeiro download. Defina ANNAS_DOWNLOAD_PATH para usar outra pasta. Deve ser um caminho absoluto, exceto que um ~ inicial representa sua pasta pessoal.

No macOS, Área de Trabalho, Documentos, Downloads e iCloud Drive são protegidos: o primeiro download lá faz o macOS perguntar se seu cliente MCP pode acessar a pasta. Se o acesso for negado, os downloads falham com [CONFIG] cannot write to the download folder; permita seu cliente em Ajustes do Sistema → Privacidade e Segurança → Arquivos e Pastas, ou escolha uma pasta diretamente na sua pasta pessoal. Evite /tmp, que o sistema operacional limpa.

Ferramentas

A IA preenche as opções de cada ferramenta a partir da sua solicitação. HOW-IT-WORKS.md lista as opções e o que cada ferramenta retorna, e --help as mostra na linha de comando.

Antes de baixar, o servidor verifica arquivos regulares concluídos diretamente na sua pasta de download contra o hash MD5 completo. Se um corresponder, ele retorna o caminho e o tamanho desse arquivo, independentemente do nome ou extensão, sem baixá-lo ou fazer uma nova solicitação de conta; downloads_left é omitido. Para downloads de artigos por DOI, o DOI é resolvido para um hash primeiro. Se nenhum arquivo local corresponder, o servidor baixa uma cópia verificada e escolhe um nome de arquivo único sem sobrescrever um arquivo existente. Um download rápido pode usar a cota da sua assinatura, que o Anna's Archive conta em uma janela contínua de 18 ou 24 horas. Baixar um arquivo novamente dentro dessa janela é gratuito, e account_status mostra quantos restam.

Solução de problemas

Os erros começam com um código:

Código	O que fazer
`[CONFIG]`	Uma variável está ausente ou inválida, o Anna's Archive rejeitou a chave secreta ou a pasta de download não pode ser gravada. Verifique Configuração.
`[UPSTREAM_BLOCKED]`	O arquivo recusou o acesso. Verifique se sua assinatura permite pesquisar. Se o erro disser que não há downloads rápidos restantes, aguarde a janela passar; `account_status` mostra a cota. Se o login em si falhou, veja Entrando.
`[NOT_FOUND]`	Nada correspondeu, ou essa cópia não tem download rápido. Tente outra consulta ou outra cópia dos resultados da pesquisa.
`[INVALID_ARGUMENT]`	Corrija o hash, DOI, id, filtro, ordenação, página, limite ou tempo limite.
`[REQUEST_TIMEOUT]`	Tente novamente ou aumente `timeout_seconds`.
`[UPSTREAM]`	O arquivo ou um servidor de download falhou. O erro informa qual e por quê; tente novamente mais tarde.

Um download com falha lista cada servidor tentado e por que cada um falhou. O servidor só verifica suas credenciais quando você pesquisa ou baixa, não quando inicia.

Se o servidor não iniciar, execute npx -y annas-mcp --version em um terminal para ver o erro. O lançador descompacta os lançamentos com o tar do sistema, que macOS, a maioria das distribuições Linux e Windows 10 ou posterior incluem.

Linha de comando

Cada ferramenta também é um comando. Defina as mesmas variáveis (ou coloque-as em um arquivo .env) e então:

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

Adicione --include-stats a uma pesquisa de livro ou artigo para incluir contagens de download, lista, votos de qualidade, relatórios e comentários por arquivo, quando disponíveis. Adicione --json para saída legível por máquina, --timeout 10m para alterar o tempo limite e --help a qualquer comando para todas as suas opções.

Privacidade

O annas-mcp roda na sua máquina e não tem telemetria. Ele envia sua chave secreta (e cookie, se você definir um) apenas para o Anna's Archive, e baixa arquivos dos servidores para os quais o Anna's Archive o aponta. Consultas de DOI podem contatar doi.org. O lançador npx e o MCP Bundle contatam o GitHub para buscar e verificar binários de lançamento. Além dos arquivos baixados, ele armazena apenas o binário de lançamento, a sessão salva e a saúde recente dos espelhos, tudo na pasta de cache. Perguntas: abra uma issue.

Contribuindo

Veja CONTRIBUTING.md para compilar a partir do código-fonte, testes e lançamentos.

Créditos

A ideia deste projeto vem do iosifache/annas-mcp, que primeiro expôs o Anna's Archive como um servidor MCP. Este repositório é uma reescrita completa e não compartilha código com ele.

Licença

MIT