Skip to main content
Glama

ao3-mcp

PyPI CI Python 3.10+

ao3-mcp MCP server

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.

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

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.

Related MCP server: FreeSearch MCP Server

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:

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.

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.

Hosting it instead of spawning it (this fork)

Upstream runs over stdio only — it is a process your MCP client spawns, so there is no URL to point a remote client at. This fork adds an opt-in Streamable-HTTP mode:

pip install .
MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 24) python server.py
# → MCP endpoint: http://0.0.0.0:8000/mcp
# → health check: http://0.0.0.0:8000/healthz

Env var

What it does

MCP_TRANSPORT

stdio (default — upstream behaviour) or http

PORT

bind port in http mode (Render sets this)

MCP_PATH

endpoint path, default /mcp

MCP_AUTH_TOKEN

if set, every MCP request must carry Authorization: Bearer <token>. Set it on anything public — otherwise you are hosting an open AO3 scraper on your own bill

Deploy on Render (free tier is enough to test): build pip install ., start MCP_TRANSPORT=http python server.py, health check path /healthz.

render.yaml in this repo describes exactly that service (pip install -r requirements.txt, python server.py --transport http --port $PORT, health check /healthz, bearer token generated by Render), so New → Blueprint pointing at this repo is the whole setup. Render suspends every free service in a workspace once its 750 monthly instance hours are gone, and resumes them on the 1st of the next month — a suspended ao3-mcp usually means "out of hours", not "broken deploy".

Tests run offline

tests/test_offline.py stubs the client's single network choke point (AO3Client._get) with recorded-style pages, so pytest never touches archiveofourown.org. That matters: AO3 gates by egress IP, and a host that trips it can stay 418'd for a long time. To check whether the deployed host can reach AO3 at all, call /probe on the service instead — it lives on Render, not on your laptop.

Two things differ from stdio:

  • The HTTP transport is stateless (no Mcp-Session-Id), so a restart or a free-tier cold start cannot leave a client holding a dead session id and 404-ing forever.

  • read_works takes minutes (sequential 0.6s-throttled downloads, then one reader call per fic). Any host with a 60s request ceiling — Vercel Hobby, most serverless — will cut it off. Only search_works / find_tags / get_work fit that budget.

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.

pip install ao3-mcp

Add to your agent

Point command at ao3-mcp and pass your key with --api-key:

{
  "mcpServers": {
    "ao3": {
      "command": "ao3-mcp",
      "args": ["--api-key", "YOUR_GEMINI_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:

"env": { "GEMINI_API_KEY": "YOUR_GEMINI_KEY" }
claude mcp add ao3 -- ao3-mcp --api-key YOUR_GEMINI_KEY

Cursor Settings → MCP → New MCP Server, paste the JSON config above.

Add the JSON config above to .gemini/antigravity/mcp_config.json.

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

Then just ask:

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

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, …).

find_tags

Live autocomplete — fuzzy wording → canonical AO3 tag, fandom, ship, or character names.

get_work

Full metadata card for one work: tags, stats, summary, series info.

read_works

Reads 1–20 full fics with the secondary model and returns a structured report per fic — plot, characters, style, verbatim prose samples, content notes — plus a comparison ranking them against your question.

Fic downloads are cached locally for 24h, so re-reading a fic with a new question costs no AO3 requests.

Good to know

  • AO3 has no API — this scrapes its (clean) HTML, one request at a time, throttled to one every 0.6s by default (tune with --min-interval) and honoring Retry-After. AO3 is volunteer-run; the politeness is deliberate.

  • Cloudflare: AO3 blocks plain HTTP clients. This uses curl_cffi with a mobile-Safari TLS fingerprint, which passes as of writing. If requests start failing with 403 + cf-mitigated: challenge, change IMPERSONATE in ao3.py.

  • Privacy: fic text goes to Google's Gemini API for reading; nothing else leaves your machine, no telemetry.

  • Adult content: AO3 hosts works across all ratings. The server passes through whatever your search scopes — use the rating filter and AO3's warning tags to control what gets fetched.

Make it yours

It's a small, single-purpose server — a few hundred readable lines with no framework magic. Fork it and edit anything: rewrite the reader's prompt, swap in a different model, change the throttle, add a tool. That's the intended way to use it.

Run it from source:

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

Credits

License

All rights reserved — this repository is not MIT. LICENSE holds the terms; NOTICE carries the MIT notice for the files inherited from the upstream fork, which has to stay with that code.

Available Tools

5 tools
find_tagsA

Resolve fuzzy wording to canonical AO3 tag names (live autocomplete).

Use before search_works when unsure of exact spelling — e.g. "coffee shop" resolves to "Alternate Universe - Coffee Shops & Cafés".

Args: term: partial/fuzzy tag text, e.g. "enemies to", "coffee", "kakashi". kind: what to complete: tag | fandom | relationship | character.

Inputs: term (required), kind. Returns: result

get_workA

Get the full metadata card for one work: tags, stats, summary, series info.

Args: work_id: the numeric AO3 work id (from search results or a URL like archiveofourown.org/works/12345).

Inputs: work_id (required). Returns: result

get_work_textA

⚠️ NOT RECOMMENDED — escape hatch only. Returns the raw full text of ONE fic directly to you, bypassing the mini reader.

Prefer read_works in almost every case. A fic can run 150k+ words; pulling that into your own context buries everything else, burns your tokens, and throws away the whole reason this server exists — delegating reading to a cheap second model. read_works hands you a structured report plus verbatim prose samples, which is enough to judge, compare, and recommend a fic without the fic ever entering your context.

Only reach for this when you genuinely need exact wording a report can't carry — e.g. the user explicitly asks you to quote or close-read a specific passage. If you just want to know what a fic is like or whether it's good: use read_works instead.

Args: work_id: the numeric AO3 work id. max_words: cap the text to the first N words (0 = whole fic). Set a limit to sample a fic's opening instead of dumping the entire thing into your context — a few thousand words is usually plenty to judge voice.

Inputs: work_id (required), max_words. Returns: result

read_worksA

Have the mini reader (a separate AI) read full fics and report on each.

Works for a single fic or up to 20 at once. You never receive fic text — only structured reader reports, one per work. The reader answers your query directly (anything works: "is the ending happy?", "how explicit is it?", "which of these should I read first?") plus gives a general digest of plot, characters, style, and content notes. When given several fics, it ends with a comparison section ranking them against your query.

This is the ONLY approved way to read a fic. A separate model does the reading so a whole novel never touches your context. You MUST send fics here before you recommend, rank, summarize, or judge them — search blurbs are not enough, and reading raw text yourself defeats the entire point of this server. Shortlist from blurbs, read here, then recommend.

Reading depth: a single-fic call sends the reader up to ~150k words (whole novels fit); in a batch each fic is capped at ~100k characters. If a long fic's report matters, read it alone. Batches that exceed the token budget are split internally, then a final reduce pass still produces ONE global comparison across the whole batch.

Content refusals: the reader is Gemini, which has a non-configurable safety filter that occasionally refuses explicit or extreme fics — that fic's report comes back as "(mini reader returned no text …)". The server already retries once on the backup model, but the block is intermittent, so if a fic you care about is refused: read it ALONE (a single fic isn't dragged down by an extreme one sharing its batch), or just retry. In a mixed batch, one refused fic does not sink the others — their reports still return.

Args: work_ids: 1-20 numeric AO3 work ids (from search results or URLs). query: the question to answer about each fic.

Inputs: query (required), work_ids (required). Returns: result

search_worksA

Search AO3 for works. All filters optional; combine freely.

RECOMMENDATION WORKFLOW — reading before recommending is MANDATORY, and the reading is done by a SEPARATE model, not you. Blurbs are author-written ads; never recommend, rank, or summarize a fic from its blurb alone. Cast a wide net (pages=2-3, i.e. 40-60 blurbs), shortlist the promising ones, then hand the top ≤20 ids to read_works — a second AI reads them and reports back. Recommend ONLY fics that came back from read_works. Do not read fic text yourself; delegating it is the entire point of this server.

SEARCH STRATEGY — searching is cheap and reading is delegated, so the winning move is always to OVER-FETCH and let read_works brute-force the shortlist, never to craft one perfect narrow query. Filters multiply: each one you add cuts the pool, and stacked filters routinely cut it to zero.

USE WILDCARDS LIBERALLY — abuse them. A * matches any run of characters and works in EVERY name field (fandom, relationship, character, tags) and in query. Wrapping a term in stars is the single best defence against AO3's exact-canonical-name trap: fandom="Genshin Impact (Video Game)" returns ZERO (the canonical tag is actually "原神 | Genshin Impact (Video Game)"), but fandom="*Genshin Impact*" returns the whole fandom. Likewise relationship="*Kazuha*Scaramouche*", tags="*Enemies to Lovers*". When you don't know the exact canonical name — which is most of the time — reach for a wildcard first instead of guessing the literal string.

IF YOU GET 0 (or few) RESULTS, that is almost always your query being too narrow, NOT the content missing from AO3. Recover instead of giving up:

  • FIRST, wildcard the name fields (*Genshin Impact*). This fixes the most common cause — an exact-match field that didn't match the canonical tag — in one retry, without a separate find_tags round-trip.

  • Still unsure of a name? find_tags resolves it, or move the idea into query as free text (fuzzy, no canonical spelling needed).

  • Drop filters one at a time and retry: word_count first, then complete_only, then rating. Re-add only what the user insisted on.

  • Concepts don't need to be tags at all: "slow burn rivals in a bakery" works fine as free-text query even if no such tag exists.

  • Still thin? Search the broad version (fandom + category, sort by kudos), fetch 2-3 pages, and let the blurbs + read_works do the filtering. A human reader has to search narrowly because they can only read a few fics; you can read twenty at once, so breadth costs you nothing.

Results show numeric work ids, not URLs. When relaying a work to the user, build the link yourself: https://archiveofourown.org/works/{id}

Each result shows a kudos-to-hits ratio (k/h) — AO3's most honest quality proxy, since kudos are one-per-reader but hits count every visit. Compare it only within similar works: multi-chapter fics accumulate hits on every chapter visit, so long WIPs run structurally lower ratios than one-shots.

Args: query: free-text search. Supports AO3's full operator syntax (case-sensitive, space after colon required where shown): "exact phrase", AND / OR / NOT, -term to exclude; words>10000, words:1000-5000, kudos>500 (same for hits/ comments/bookmarks); sort:kudos, sort:hits, sort:>posted (oldest first); otp: true (exactly one ship, no side pairings); creators: username / -creators: username; summary: "phrase"; expected_number_of_chapters: 1 (one-shots only); series.title: * (part of a series); language_id: en. Also supports * wildcards, e.g. *coffee shop*. ⚠️ query is a FULL-TEXT match on the fic body, AND'd with every other filter — so it narrows HARD. Do NOT stuff mood/concept synonyms here ("nuzzle OR forehead kiss OR won't let go"): that demands the prose literally contain one of those strings on top of your tag/fandom filters, and routinely collapses a healthy 60-result search to 0. Concepts belong in tags (wildcarded), not here. Use query for author names, quoted title/summary phrases, or the numeric operators above — leave it EMPTY when a tag already covers the vibe. title: words in the work title. author: author/creator name. fandom: fandom name, e.g. "Naruto" (comma-separate several). Exact canonical match — but * wildcards work here: prefer "Genshin Impact" over the literal name to survive canonical tags with prefixes/aliases (e.g. "原神 | Genshin Impact (Video Game)"). relationship: ship tag. Format: "A/B" romantic, "A & B" platonic, canonical name order, e.g. "Kakashi Hatake/Iruka Umino". Wildcards work: "KazuhaScaramouche*" beats guessing the exact tag order. character: character name(s), comma-separated. Wildcards work here too. tags: freeform tags, comma-separated, EXACT canonical spelling (use find_tags to resolve, or wildcard it: "Enemies to Lovers"). Popular canonical tags: Fluff; Angst; Hurt/Comfort; Emotional Hurt/Comfort; Angst with a Happy Ending; Hurt No Comfort; Enemies to Lovers; Friends to Lovers; Enemies to Friends to Lovers; Slow Burn; Mutual Pining; Fake/Pretend Relationship; There Was Only One Bed; Idiots in Love; Getting Together; Established Relationship; First Kiss; Found Family; Fix-It; Time Travel; Kid Fic; Domestic Fluff; Tooth-Rotting Fluff; Crack; Crack Treated Seriously; 5+1 Things; POV Outsider; Soulmates; Smut; Plot What Plot/Porn Without Plot; Alpha/Beta/Omega Dynamics; Dead Dove: Do Not Eat; Canon Compliant; Post-Canon; Alternate Universe - Modern Setting; Alternate Universe - Canon Divergence; Alternate Universe - Coffee Shops & Cafés; Alternate Universe - College/University; Alternate Universe - Soulmates. rating: one of: general, teen, mature, explicit, not rated. categories: comma-separated relationship categories to include: F/F, F/M, Gen, M/M, Multi, Other. Empty = all. complete_only: only finished works. word_count: range like "10000-50000", ">5000" or "<20000". sort_by: relevance | kudos | hits | comments | bookmarks | words | date_updated | date_posted. page: which result page to start from (for paging through results). pages: result pages to fetch, 20 works each (1-5). For a targeted lookup 1 is enough; for a recommendation hunt fetch 2-3 pages (40-60 blurbs) so the read_works shortlist has real competition.

Inputs: page, tags, pages, query, +10 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: search_works discovers works, find_tags resolves canonical names, get_work retrieves metadata, read_works delegates fic reading, and get_work_text is an explicitly discouraged raw-text escape hatch. The overlap between read_works and get_work_text is called out directly and bounded by clear usage guidance, so an agent can reliably choose between them.

    Naming Consistency5/5

    All tool names use consistent snake_case and follow a predictable verb_noun pattern: search_works, find_tags, get_work, read_works, get_work_text. The only variation is get_work_text adding a third noun to distinguish the raw-text escape hatch, which is still readable and consistent.

    Tool Count5/5

    Five tools is well-scoped for an AO3 search-and-reading assistant. Each tool earns its place and supports a distinct stage of the discovery, tag resolution, metadata inspection, reading, and fallback workflow.

    Completeness5/5

    The tool set covers the apparent domain end to end: search, tag canonicalization, work metadata, delegated reading, and a raw-text escape hatch for exact quoting. For the stated recommendation workflow, there are no obvious missing operations or dead ends.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI models to search and retrieve up-to-date technical documentation for major agent frameworks (such as LangChain, LlamaIndex, AutoGen, Agno, OpenAI Agents SDK, MCP docs, Camel-AI and CrewAI) by running scoped Google searches and parsing the resulting pages. It can be deployed locally over stdio or remotely over SSE.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives AI assistants keyless web search, news search, and full-page reading tools by querying multiple engines in parallel and returning merged results. It can run locally over stdio or remotely over HTTP for Claude, Cursor, and other agents.
      4
      MIT
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables AI agents to search and filter titles, browse rankings, read comments, manage favorites, download albums, chapters, and covers with live progress, cancellation, and retry, and convert downloads into ZIP, PDF, or long images, all through natural language. Exposes 21 tools and 3 knowledge resources over stdio, SSE, and HTTP transports, along with runtime configuration and account login.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Exposes 21 tools and 3 knowledge resources so AI agents can search, browse, and download albums, manage favorites and comments, query rankings, and convert downloaded content into ZIP, PDF, or long images, with background task control and retry support. It supports stdio, SSE, and HTTP transports alongside runtime configuration updates and account login with cookie persistence.
      -