ao3-mcp

ao3-mcp

一个 MCP（Model Context Protocol）服务，可将 AI Agent——Claude、Cursor 或任何 MCP 客户端——连接到 Archive of Our Own。使用完整筛选条件搜索 AO3 同人小说，将模糊措辞解析为规范标签，并获取实际读过的作品再进行推荐。

诀窍在于：你的 Agent 从不读取同人小说文本，而是将阅读任务交给一个低成本的辅助模型（Gemini），由它消化整部作品——甚至是 15 万字的长篇小说——并返回结构化报告。Agent 的上下文始终保持清爽；推荐基于真实文本，而非简介。

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 个结果），让阅读模型阅读候选列表——一次调用最多阅读 20 部完整作品——然后只推荐实际读过的作品，并附上原文摘录，从文本本身判断质量。

不只是帮你寻找下一本作品

如果你用 AI 写作——同人小说、原创小说或角色扮演——它还能兼作灵感引擎。在场景进行到一半时，你的 Agent 可以找出真实同人作者如何处理你正在描写的特定情节：

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

添加到你的 Agent

将 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——本工具会抓取其（简洁的）HTML，每次只发送一个请求，默认每 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 的警告标签来控制抓取内容。

按需定制

这是一个小型、用途单一的服务——只有几百行易读代码，没有框架魔法。你可以 Fork 并随意修改：重写阅读器的提示词、换用其他模型、调整请求间隔或添加工具。这正是推荐的使用方式。

从源代码运行：

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。
• 所有同人作品均归 Archive of Our Own 上的作者所有；该网站是 Organization for Transformative Works 的项目。

许可证

MIT