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以上（推奨）	✅	✅

AIで検索とダウンロードの両方を行うには、Lucky Librarian以上をおすすめします。 ベーシックプランでは、各書籍のダウンロードURLを手動で貼り付ける必要があります。

免責事項：私はAnna's Archiveとは無関係です。大規模なDDoS攻撃により、2026年に厳格なスクレイピング対策が導入され、有料会員のみが対象外となりました。

MCPのセットアップ · CLIのセットアップ · Go SDK

メンバーシップのシークレットキーを使ってサインインし、セッションを自動で更新するため、ブラウザーからCookieをコピーする必要はありません。iosifache/annas-mcpから移行する場合は、切り替えは1行の変更で済みます。

ツール	機能
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 FAQ）。

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ではシークレットキーの入力を求められます。キーはシステムのキーチェーンに保存されます。その後、任意の設定を2つ求められます。スキップするには 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" の前に自分のユーザー ID とグループ ID を指定した "--user", "1000:1000" を追加します。

試してみる

クライアントを再起動して、「『高慢と偏見』の EPUB を探してダウンロードして」のように尋ねます。AI が検索してコピーを選び、ファイルの保存先を伝えます。保存先は、別の場所を選択していない限り、ホームフォルダー内の annas-archive です。

CLI の設定

1つのパッケージで両方のコマンドをインストールします。

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 からの移行

このサーバーは従来と同じ4つのツールを維持し、さらに3つを追加しています。また、同じ 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回終了します。セッションは保存され、実行の間も維持されます。

サインインに失敗した場合、エラーメッセージには各ミラーからの応答と、代わりにブラウザーのセッションをサーバーに渡す方法が表示されます。

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 は保護されています。これらの場所への最初のダウンロード時に、MCP クライアントによるフォルダーへのアクセスを許可するかどうかを macOS が確認します。アクセスが拒否されると、ダウンロードは [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を使用してリリースを展開します。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に接続します。ダウンロードしたファイルを除き、保存するのはリリースバイナリ、保存済みセッション、最近のミラーの稼働状況のみで、いずれもキャッシュフォルダーに保存されます。ご質問はこちら：イシューを作成。

コントリビューション

ソースからのビルド、テスト、リリースについては、CONTRIBUTING.mdを参照してください。

クレジット

このプロジェクトのアイデアは、Anna's ArchiveをMCP サーバーとして初めて公開したiosifache/annas-mcpに由来します。このリポジトリは全面的に書き直されたもので、元のリポジトリとはコードを共有していません。

ライセンス

MIT