Claude Code

\n\n```bash\nclaude mcp add ao3 -- ao3-mcp --api-key YOUR_GEMINI_KEY\n```\n\n

\n\n

Cursor

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

\n\n

Google Antigravity

\n\nAdd the JSON config above to `.gemini/antigravity/mcp_config.json`.\n\n

\n\n

VS Code / Copilot

\n\n```bash\ncode --add-mcp '{\"name\":\"ao3\",\"command\":\"ao3-mcp\",\"args\":[\"--api-key\",\"YOUR_GEMINI_KEY\"]}'\n```\n\n

\n\nThen just ask:\n\n```\nFind me a completed enemies-to-lovers longfic in , read the top candidates, and tell me which is best written.\n```\n\n### Launch params\n\n| Param | Env var | Default | What it does |\n| ----------------- | --------------------- | -------------------- | --------------------------------------------- |\n| `--api-key` | `GEMINI_API_KEY` | — | Gemini API key (required). |\n| `--model` | `GEMINI_MODEL` | `gemini-flash-latest`| Model the reader uses. |\n| `--backup-model` | `GEMINI_MODEL_BACKUP` | `gemini-flash-lite-latest` | Fallback model when the main one is throttled. |\n| `--min-interval` | `AO3_MIN_INTERVAL` | `0.6` | Minimum seconds between AO3 requests. |\n\n## Tools\n\n| Tool | What it does |\n| -------------- | ---------------------------------------------------------------------------- |\n| `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`, …). |\n| `find_tags` | Live autocomplete — fuzzy wording → canonical AO3 tag, fandom, ship, or character names. |\n| `get_work` | Full metadata card for one work: tags, stats, summary, series info. |\n| `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. |\n\nFic downloads are cached locally for 24h, so re-reading a fic with a new question costs no AO3 requests.\n\n## Good to know\n\n- **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.\n- **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`.\n- **Privacy:** fic text goes to Google's Gemini API for reading; nothing else leaves your machine, no telemetry.\n- **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.\n\n## Make it yours\n\nIt'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.\n\nRun it from source:\n\n```bash\ngit clone https://github.com/ArturLys/ao3-mcp.git\ncd ao3-mcp\npython -m venv .venv\nsource .venv/bin/activate # Windows: .venv\\Scripts\\activate\npip install -r requirements.txt\n\npython smoke_test.py YOUR_GEMINI_KEY # end-to-end check: search → download → digest\npython server.py --api-key YOUR_GEMINI_KEY # or point your client's command at this\n```\n\n## Credits\n\n- AO3 access approach builds on [ao3_api](https://github.com/wendytg/ao3_api) by wendytg.\n- All fanworks belong to their authors on the [Archive of Our Own](https://archiveofourown.org/), a project of the [Organization for Transformative Works](https://www.transformativeworks.org/).\n\n## License\n\nMIT\n","changelogMarkdown","videoKey","requiredSecretsJson","publishedAt","priceCents","trialDays",0,"upstream",{"_103":104,"_105":106,"_107":108,"_109":110,"_111":-5,"_112":113},"requiredSecrets",[],"tags",[94,95,96,97,98,99,100,101,102],"assets",[],"stats",{"_92":81,"_93":81},"ratingAvg","reviewCount","ai-tools","ao3","archive-of-our-own","claude","claude-code","fandom","fanfic","fanfiction","gemini","topics",[94,95,96,97,98,99,100,101,102,118,119,120],"license","MIT","language","Python","registryName","io.github.ArturLys/ao3-mcp","homepage","packages",[114],{"_115":116,"_117":21,"_71":72},"registryType","pypi","identifier","mcp","mcp-server","model-context-protocol","ENV",{"_123":124,"_125":126,"_127":128},"ENVIRONMENT","production","TURNSTILE_SITE_KEY","0x4AAAAAAB8-rEI2gNDf_QhU","SENTRY_DSN","https://45fd1229f78089d5c3ee78be128030e1@o4510583261757440.ingest.de.sentry.io/4510584253448272"]

ao3 mcp