ao3-mcp

ao3-mcp

AI エージェント（Claude、Cursor、または任意の MCP クライアント）を Archive of Our Own に接続する MCP（Model Context Protocol）サーバーです。AO3 のファンフィクションを詳細なフィルターで検索し、あいまいな表現を正式なタグに解決して、実際に読んだ作品だけを推薦します。

ポイントは、エージェントが作品本文を読む必要がないことです。読書を低コストのセカンダリモデル（Gemini）に任せれば、15 万語の長編でも読み込み、構造化レポートを返します。エージェントのコンテキストはすっきり保たれ、推薦はあらすじではなく実際の本文に基づきます。

agent ──MCP──> server.py
                 ├─ ao3.py     AO3 scraping (no public API exists) — throttled and polite
                 └─ reader.py  Gemini reads the fics, reports back: plot, style,
                               prose samples, content notes, a ranking

あらすじベースの推薦より優れている理由

AO3 のあらすじは、作者が書いた広告です。このサーバーのワークフローでは、幅広く検索し（40～60 件）、読書モデルに候補を読み込ませます。1 回の呼び出しで最大 20 件の作品全体を読み、実際に読んだ作品だけを、本文の品質を直接評価できる引用文とともに推薦します。

次に読む作品を探すだけではありません

ファンフィクション、オリジナル小説、ロールプレイなど、AI と一緒に執筆している場合、これは発想を広げるツールにもなります。シーンの途中で、エージェントに実際の作品を検索させ、今書いているのと同じ展開を作品の作者がどう描いているかを調べられます。

Find three highly-kudosed fics where rivals are forced to share a bed, read them,
and tell me how each one builds the tension — pacing, POV, what they leave unsaid.

読書モデルは、構成、文体に関するメモ、引用文を含むレポートを返すため、モデルはファンフィクションのトロープが実際にどう書かれているかに基づいて生成できます。ファンフィクションらしさを想像で補う必要はありません。ロールプレイでも同様に、キャラクターの声を見事に表現した作品のレポートを取得し、文体の参考資料として使えます。

インストール

Python 3.10 以降と無料の Gemini API キーが必要です。

aistudio.google.com/api-keys にアクセスし、任意の Google アカウントでサインインして、**「Create API key」**をクリックします。無料枠で十分です。請求設定は不要です。

pip install ao3-mcp

エージェントに追加する

command に ao3-mcp を指定し、--api-key でキーを渡します。

{
  "mcpServers": {
    "ao3": {
      "command": "ao3-mcp",
      "args": ["--api-key", "YOUR_GEMINI_KEY"]
    }
  }
}

キーを引数リストに含めたくない場合は、--api-key を省略し、代わりに env ブロックで渡します。サーバーはフォールバックとして、環境変数から GEMINI_API_KEY を読み込みます。

"env": { "GEMINI_API_KEY": "YOUR_GEMINI_KEY" }

claude mcp add ao3 -- ao3-mcp --api-key YOUR_GEMINI_KEY

code --add-mcp '{"name":"ao3","command":"ao3-mcp","args":["--api-key","YOUR_GEMINI_KEY"]}'

あとは、次のように尋ねるだけです。

Find me a completed enemies-to-lovers longfic in <fandom>, read the top candidates, and tell me which is best written.

起動パラメーター

ツール

作品のダウンロードはローカルに 24 時間キャッシュされるため、新しい質問で作品を読み直しても AO3 へのリクエストは発生しません。

知っておくとよいこと

• AO3 に API はありません。このサーバーは AO3 の（クリーンな）HTML をスクレイピングします。デフォルトでは 1 リクエストごとに 0.6 秒の間隔を空け（--min-interval で調整可能）、Retry-After にも従います。AO3 はボランティアによって運営されているため、意図的に慎重なアクセスを行います。
• Cloudflare： AO3 は通常の HTTP クライアントをブロックします。このサーバーはモバイル版 Safari の TLS フィンガープリントを使用する curl_cffi を使っており、執筆時点ではブロックを回避できます。リクエストが 403 と cf-mitigated: challenge で失敗するようになった場合は、ao3.py の IMPERSONATE を変更してください。
• プライバシー： 読み取りのために作品のテキストを Google の Gemini API に送信します。それ以外のデータがマシンの外に送信されることはなく、テレメトリーもありません。
• 成人向けコンテンツ： AO3 にはあらゆるレーティングの作品があります。このサーバーは検索で指定した範囲の作品をそのまま取得します。取得対象を制御するには、rating フィルターと AO3 の警告タグを使用してください。

自分好みにカスタマイズする

これは小規模で単一目的のサーバーです。フレームワークの複雑な仕組みを使わず、数百行ほどの読みやすいコードで構成されています。フォークして自由に編集してください。読み取り用プロンプトを書き換える、別のモデルに切り替える、リクエスト間隔を変更する、ツールを追加するなど、思いのままにカスタマイズできます。それが想定されている使い方です。

ソースから実行します。

git clone https://github.com/ArturLys/ao3-mcp.git
cd ao3-mcp
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -r requirements.txt

python smoke_test.py YOUR_GEMINI_KEY   # end-to-end check: search → download → digest
python server.py --api-key YOUR_GEMINI_KEY   # or point your client's command at this

クレジット

• AO3 へのアクセス方法は、wendytg が開発した ao3_api を基にしています。
• すべてのファン作品は、Organization for Transformative Works のプロジェクトである Archive of Our Own に掲載されている作者に帰属します。

ライセンス

MIT