ao3-mcp is an MCP (Model Context Protocol) server for connecting AI agents—Claude, Cursor, or any MCP client—to the Archive of Our Own (AO3).
Purpose
- Search AO3 fanfiction with full filtering criteria.
- Resolve vague wording into AO3's canonical tags.
- Let the AI actually read works before making recommendations, so recommendations are based on the real text.
Main capabilities and how it works
- Your agent itself never reads the novel text; instead, it delegates the reading task to a low-cost secondary model (Gemini). That model digests the entire work—even a 150,000-word long fic—and returns a structured report. This keeps your agent's context clean, and recommendations are based on the real text rather than blurb marketing copy.
- Compared with blurb-based recommendations: AO3 blurbs are ads written by the author. This server's workflow is: search broadly (40–60 results), have the reading model read the shortlist—up to 20 full works can be read in a single call—and recommend only content that was actually read, along with verbatim original-text samples, so quality judgments come from the text itself.
- Writing and roleplay inspiration engine: if you write with AI—fanfiction, original fiction, roleplay—it can serve as an inspiration engine. While a scene is in progress, the agent can pull up how real fanfiction authors handled the specific beat you are writing; the reader returns structure, style notes, and verbatim original-text samples, so the model understands how that beat is actually written instead of guessing from imagination what fanfiction is like. The same applies to roleplay: you can pull reports on works that capture a certain character's voice, as a style reference.
How to use Dependencies: requires Python 3.10+ and a free Gemini API key. To get one: go to aistudio.google.com/api-keys, sign in with any Google account, and click "Create API key." The free quota is sufficient; no billing setup is required.
Add to your agent: point the command at ao3-mcp and pass the key via --api-key. If you do not want to put the key in the argument list, remove --api-key and pass it via an env block instead—the server reads GEMINI_API_KEY from the environment variable as a fallback.
Configuration locations:
- Cursor: Settings → MCP → New MCP Server, paste the JSON configuration.
- .gemini/antigravity/mcp_config.json: add the JSON configuration above.
Caching: work downloads are cached locally for 24 hours, so rereading the same work with a new question will not generate a new AO3 request.
Access and limitations
- AO3 has no API: this project scrapes its (clean) HTML, one request at a time, with a default throttle of once every 0.6 seconds (adjustable with --min-interval), and respects Retry-After. AO3 is run by volunteers, and this caution is deliberate.
- Cloudflare: AO3 blocks ordinary HTTP clients. This project uses curl_cffi with a mobile Safari TLS fingerprint, which works as of the time of writing. If requests start failing with 403 + cf-mitigated: challenge, modify IMPERSONATE in ao3.py.
- Privacy: work text is sent to Google's Gemini API for reading; apart from that, no other data leaves your machine, and there is no telemetry.
- Adult content: AO3 hosts content of various ratings. The server passes through whatever is within your search scope—please use rating filters and AO3's warning tags to control what you retrieve.
- Scale: this is a small, single-purpose server—a few hundred lines of readable code, with no framework magic. You can fork it and modify anything: rewrite the reader's prompts, switch to another model, change the throttling, add tools. This is the intended way to use it.
Running from source: running from source is supported.
Acknowledgments and copyright: the AO3 access method is built on wendytg's ao3_api. All fanworks belong to their authors on Archive of Our Own, and AO3 is a project of the Organization for Transformative Works.
