ArturLys/ao3-mcp

An MCP (Model Context Protocol) server that connects AI agents — Claude, Cursor, or any MCP client — to the Archive of Our Own. Search AO3 fanfiction with full filters, resolve fuzzy wording to canonical tags, and get fics *actually read* before they're recommended.
The trick: your agent never reads fic text. It delegates reading to a cheap secondary model (Gemini), which digests whole fics — even 150k-word novels — and returns structured reports. Your agent's context stays clean; the recommendations are based on the real text, not the blurb.
Why this beats blurb-based recommendations
An AO3 blurb is an ad written by the author. This server's workflow is: search wide (40–60 results), have the reader model read the shortlist — up to 20 full fics in one call — and recommend only what was actually read, with verbatim prose samples so quality is judged from the text itself.
Not just for finding your next read
If you write with an AI — fanfic, original fiction, roleplay — this doubles as an inspiration engine. Mid-scene, your agent can pull up how real fic authors handle the exact beat you're on:
The reader reports back with structure, style notes, and verbatim prose samples, so the model gets grounded in how the trope is actually written — not what it imagines fanfic sounds like. Works the same for roleplay: pull reports on fics that nail a character's voice and feed them in as style reference.
Install
Requires **Python 3.10+** and a free **Gemini API key**:
> Go to aistudio.google.com/api-keys, sign in with any Google account, and click **"Create API key"**. The free tier is enough — no billing setup needed.
Add to your agent
Point command at ao3-mcp and pass your key with --api-key:
Prefer to keep the key out of the args list? Drop --api-key and pass it in an env
block instead — the server reads GEMINI_API_KEY from the environment as a fallback:
Claude Code
Cursor
Cursor Settings → MCP → New MCP Server, paste the JSON config above.
Google Antigravity
Add the JSON config above to .gemini/antigravity/mcp_config.json.
VS Code / Copilot
Then just ask:
Launch params
| Param | Env var | Default | What it does |
| ----------------- | --------------------- | -------------------- | --------------------------------------------- |
| --api-key | GEMINI_API_KEY | — | Gemini API key (required). |
| --model | GEMINI_MODEL | gemini-flash-latest| Model the reader uses. |
| --backup-model | GEMINI_MODEL_BACKUP | gemini-flash-lite-latest | Fallback model when the main one is throttled. |
| --min-interval | AO3_MIN_INTERVAL | 0.6 | Minimum seconds between AO3 requests. |
Tools
| Tool | What it does |
| -------------- | ---------------------------------------------------------------------------- |
| search_works | Search AO3: fandom, ship, character, tags, rating, word count, completion, sorting. 20 results/page, up to 5 pages per call. The query field supports AO3's full search-operator syntax (words>10000, kudos>500, sort:kudos, …). |