{
  "markdown": "# myfigurecollection-api\n\nAn unofficial [MyFigureCollection.net](https://myfigurecollection.net) API: a Python\nlibrary plus a local **MCP server**, so agents can read figure data, collections,\nlists and clubs.\n\nMFC has no working public API. Its own API club ([#349](https://myfigurecollection.net/club/349))\nhas been promising \"API v4 coming soon\" for eight years. This package reads the\npublic HTML instead, and turns it into typed models.\n\n## New here? The short version\n\nMyFigureCollection is the largest catalog of anime figures and merch on the\ninternet, and for years there has been no good way for a program to read it.\nThis project fixes that on your own computer. You install it once, and an AI\nassistant like Claude can then look things up on MFC for you: \"how much is this\nfigure at AmiAmi?\" or \"list every Chiikawa item releasing in October.\"\n\n```mermaid\nsequenceDiagram\n    participant You\n    participant Claude\n    participant api as mfc-api, on your computer\n    participant MFC as myfigurecollection.net\n    You->>Claude: How much is the Alice Carroll figure?\n    Claude->>api: get_partner_listings(287)\n    api->>MFC: fetch the item's Buy window\n    MFC-->>api: HTML\n    api-->>Claude: AmiAmi · Available · ¥11,980\n    Claude-->>You: AmiAmi has it in stock for ¥11,980\n```\n\n**What is MCP?** The Model Context Protocol is a standard plug for giving AI\nassistants new abilities. An MCP server is a small program on your machine that\nan assistant is allowed to call. This one gives your assistant 12 MFC abilities,\nfrom item search to barcode lookup. Adding it takes one snippet in a config\nfile, shown in [Use it as an MCP server](#use-it-as-an-mcp-server).\n\n**Why not use MFC's official API?** There isn't one. The site's own API club\nhas been waiting for it since 2018.\n\n**Why isn't this a website I can visit?** Cloudflare guards MFC and decides who\ngets in partly by IP reputation. It trusts connections from home computers and\ndistrusts servers, so a hosted version would get blocked within days while a\ncopy on your own machine keeps working. That constraint shaped the whole\ndesign.\n\n**Do I need to know Python?** Two terminal commands to install (below). After\nthat your assistant does the driving.\n\n## Why this exists (and why the obvious approach fails)\n\nMFC is behind Cloudflare, which blocks on **TLS fingerprint** — not user-agent.\n`requests`, `httpx` and `aiohttp` all get a 403 \"Just a moment...\" challenge no\nmatter what headers you send. That is why the older `tenji` scraper stopped\nworking; its parsers never even received HTML.\n\nThis package uses [`curl_cffi`](https://github.com/lexiforest/curl_cffi) with\n`impersonate=\"chrome\"`, which reproduces a real Chrome handshake and gets a 200.\n**That choice is load-bearing.** Swapping in a normal HTTP client will break\neverything.\n\nIt is also why this ships as a *local* tool rather than a hosted service:\nCloudflare weights IP reputation, so a scraper on datacenter IPs gets challenged\nand burns the shared address for everyone. Run it on your own machine.\n\n```mermaid\nflowchart LR\n    A[\"requests / httpx / aiohttp<br/>(any headers you like)\"] -->|\"403 Just a moment...\"| CF{Cloudflare}\n    B[\"Your browser\"] -->|200| CF\n    C[\"mfc-api via curl_cffi<br/>(Chrome TLS handshake)\"] -->|200| CF\n    CF --> MFC[(\"myfigurecollection.net\")]\n```\n\n## Install\n\nThis needs **Python 3.10+**. The package is on PyPI:\n\n```bash\npip install myfigurecollection-api\n```\n\nOn a Mac, `python3` is often Xcode's 3.9, which will not run this code, so be\nexplicit about the interpreter (e.g. `pip3.12`). Working from a clone instead,\nuse `pip3.12 install -e .`.\n\nThen check it landed:\n\n```bash\nmfc-api item 287\n```\n\nIf `mfc-api` isn't found, your shell's `python3` bin directory isn't on `PATH`. Find the\nscript with `python3.12 -c \"import sysconfig; print(sysconfig.get_path('scripts'))\"` and\nuse that absolute path.\n\n## Use it as an MCP server\n\n`mfc-api` with no arguments starts the MCP server on stdio. Add this to your MCP config —\n`~/Library/Application Support/Claude/claude_desktop_config.json` for Claude Desktop, or\n`.mcp.json` in your project for Claude Code:\n\n```json\n{\n  \"mcpServers\": {\n    \"myfigurecollection\": {\n      \"command\": \"uvx\",\n      \"args\": [\"myfigurecollection-api\"]\n    }\n  }\n}\n```\n\nThis needs [`uv`](https://docs.astral.sh/uv/) installed; `uvx` fetches the package\nfrom PyPI on first run, so there is nothing else to set up.\n\nNo `uv`? Point `command` at the installed script by its **absolute path**, e.g.\n`/Library/Frameworks/Python.framework/Versions/3.12/bin/mfc-api`. The path must be\nabsolute because MCP clients launch servers with a minimal `PATH` that does not\ninclude your shell's Python bin directory — a bare `\"command\": \"mfc-api\"` will fail\neven though it works in your terminal.\n\n### Tools\n\n| Tool | What it returns |\n|---|---|\n| `get_item(item_id)` | Full item: category, picture, origins, characters, companies, artists, releases (date / edition / price / barcode), scale, height, rating, owner counts |\n| `search_items(query, page, category_id)` | 50 items per page, with pagination |\n| `search_by_barcode(barcode)` | Item lookup by JAN/UPC — the join key for matching an item across stores |\n| `get_partner_listings(item_id)` | Which partner shops sell an item, with availability and price |\n| `get_shop(shop_id)` | Homepage, location, shipping, rating, review and item counts |\n| `search_shops(keywords, page, average_score, partners_only)` | The shop directory, 10 per page |\n| `get_profile(username)` | Join date, hits, rank, about fields, per-category collection counts |\n| `get_collection(username, status, page)` | 50 items per page; `status` is `owned`, `ordered`, `wished` or `favorites` |\n| `get_user_lists(username, page)` | A user's published item lists |\n| `get_list(list_id, page)` | A list's owner, description, tags and items |\n| `get_club(club_id)` | Description, threads, recent comments, staff, members |\n| `get_club_members(club_id, page)` | The full member roster |\n\n`get_club` is new — `tenji` never had it.\n\n### Two things to know about store data\n\n**Prices only exist where MFC has a barcode.** `get_partner_listings` returns every\npartner shop, but MFC can only check real stock for items whose JAN it recorded. For an\nitem with no barcode, all 32 partners come back as `maybe_available` with no price.\n**That means \"not checked\", not \"in stock\".** Filter on `availability == \"available\"`.\n\n**`search_by_barcode` is a lookup, not a search.** A known barcode returns the full item\nunder `item` with `matched: true`. An unknown one returns `matched: false` — which\nincludes barcodes that are real but that MFC simply never recorded, common for Western\nreleases.\n\n### Configuration\n\n| Environment variable | Default | Meaning |\n|---|---|---|\n| `MFC_API_RATE_LIMIT` | `1.0` | Seconds between requests |\n| `MFC_API_CACHE_TTL` | `3600` | Cache lifetime in seconds; `0` disables |\n| `MFC_API_CACHE_DIR` | `~/.cache/mfc-api` | Where cached pages live |\n| `MFC_API_LOG_LEVEL` | `WARNING` | Server log level (logs go to stderr) |\n\n## Use it as a library\n\n```python\nfrom mfc_api import MFCClient, CollectionStatus\n\nwith MFCClient() as mfc:\n    item = mfc.get_item(287)\n    print(item.name)                       # Aria - Alice Carroll - Maa - 1/6 (Toy's Works)\n    print(item.releases[0].price)          # 6980.0\n    print([c.name for c in item.characters])  # ['Alice Carroll', 'Maa']\n\n    collection = mfc.get_collection(\"Climbatize\", status=CollectionStatus.OWNED)\n    print(collection.stats.owned, collection.pagination.total_pages)\n\n    # Walk every page, politely (one request per second)\n    for page in mfc.iter_collection(\"Climbatize\", max_pages=3):\n        print(page.pagination.current_page, len(page.items))\n```\n\nBarcode in, prices out:\n\n```python\nfrom mfc_api import MFCClient\n\nwith MFCClient() as mfc:\n    match = mfc.search_by_barcode(\"4543341130624\")\n    if match.matched:\n        for listing in mfc.get_partner_listings(match.item.id).available:\n            print(listing.shop_name, listing.price, listing.currency)  # AmiAmi 11980.0 JPY\n```\n\n## Use it from the shell\n\n```bash\nmfc-api item 287\n```\n\n```bash\nmfc-api barcode 4543341130624\n```\n\n```bash\nmfc-api listings 287\n```\n\n```bash\nmfc-api shops Japan --partners\n```\n\n```bash\nmfc-api collection Climbatize --status owned --page 2\n```\n\nEverything prints JSON on stdout; logs go to stderr. `mfc-api --help` lists every\nsubcommand. `mfc-api-cli` is kept as an alias.\n\n## Archiving an item page to the Wayback Machine\n\nA price or a listing you read today is uncitable tomorrow: the page will have\nmoved on, and nobody has to take your word for what it said. `archive=True`\nfiles the **public item page** with the Internet Archive's Save Page Now and\nattaches the result to the item.\n\n```python\nwith MFCClient() as mfc:\n    item = mfc.get_item(287, archive=True)\n    print(item.releases[0].price, item.archive.wayback_url)\n    # 6980.0 https://web.archive.org/web/20260903081500/https://myfigurecollection.net/item/287\n```\n\nThree things fall out of one hook: a price-history series accumulates as a\nbyproduct of ordinary reads, every row becomes auditable by someone who does not\ntrust you, and the data survives the site. That last one is not hypothetical —\n`tenji` died, and Mandarake went dark in September 2026.\n\n**It never breaks a read.** A failure is a row, not an exception:\n`item.archive.status` is one of `success`, `already` (a recent capture existed,\nso the Archive declined to make another — still a preservation success),\n`skipped`, `pending`, or `failed` with a `reason`. If the Internet Archive is\ndown you still get the item.\n\n### Nothing about a person is ever archived\n\nMost of MFC is people. `is_public_item_url` is a **whitelist** of `/item/<id>`\nwith no query string, so profiles, collections, user lists and club rosters are\nrefused before any request is made:\n\n```python\nmfc.snapshot(\"https://myfigurecollection.net/item/287\")       # captured\nmfc.snapshot(\"https://myfigurecollection.net/profile/someone\")  # skipped, never sent\n```\n\nA whitelist rather than a blacklist on purpose: a new personal URL shape cannot\nleak through something that only lists what to keep.\n\n### It is opt-in for a reason\n\nReads default to `archive=False`, and archiving is meant to run as its own\ndeliberate pass over the items you actually care about — not inline in a\nlatency-sensitive loop:\n\n- **Weekly cadence.** A JSON ledger records when each URL was last captured;\n  anything captured in the last 7 days is skipped without a request. Weekly is\n  plenty of resolution for a price curve and much gentler on both the Archive\n  and MFC. The submit also carries `if_not_archived_within=7d`, so the Archive\n  enforces the same window even if the ledger is lost.\n- **Serialized, one every 6 seconds**, with a per-run cap of 50, and\n  `Retry-After` honoured on a 429.\n\n| Setting | What it does |\n|---|---|\n| `MERCH_ARCHIVE=0` | Kill switch — disables every snapshot in the process. Shared with the sibling merch clients, so one variable turns archiving off across a bulk run. |\n| `MERCH_ARCHIVE_LEDGER` | Ledger path, shared across sibling clients so one pass keeps one honest cadence per URL. |\n| `MFC_ARCHIVE_LEDGER` | Ledger path for this package only. Default: `<cache dir>/archive-ledger.json`. |\n| `IA_ACCESS_KEY` / `IA_SECRET_KEY` | Internet Archive S3 keys. Free, from [archive.org/account/s3.php](https://archive.org/account/s3.php). On macOS they are also read from the Keychain services `ia-s3-access` / `ia-s3-secret`. |\n\nWithout credentials the result is `status=\"failed\"` with a reason naming the\nfix — not a crash, and not a silent no-op.\n\nBuild one `Archiver` per pass and reuse it (the client does this for you), so\nthe rate limiter and the per-run cap apply across the whole batch rather than\nresetting each time.\n\n## Being a good citizen\n\n- Rate-limited to **1 request/second** by default, process-wide.\n- Responses are cached on disk for an hour, so repeated agent calls cost nothing.\n- Read-only. There are no login, write, or vote operations, and none are planned.\n- Wayback snapshots are opt-in, weekly per URL, capped per run, and restricted\n  to `/item/<id>` pages — never a profile, collection, list or club page.\n\nIf you scrape MFC hard enough to be noticed, Cloudflare will start challenging\nyour IP, and you will have made the site worse for everyone. Don't.\n\n## Tests\n\n```bash\npython3 -m pytest\n```\n\nThe default run is entirely offline — parser tests read saved HTML fixtures\ncaptured on 2026-07-30. Tests that hit the live site are marked `live` and\ndeselected by default:\n\n```bash\npython3 -m pytest -m live\n```\n\nRun those when MFC's markup may have changed; they are the canary.\n\n## Credits\n\nThe parser architecture — a parser class per page, given HTML, returning a\nmodel — is ported from [`tenji`](https://pypi.org/project/tenji/) by\n**Nate Shoffner** (MIT). The selectors are not: MFC's templates moved on since\ntenji's last release. Two endpoints tenji used are gone entirely\n(`itemlists.v4.php` now 404s), and the collection, profile, list and shop pages\nall render different markup than it expects.\n\nOne piece of tenji did survive verbatim: the Buy window is still a form POST to\n`/item/{id}` with `commit=loadWindow&window=buyItem`, answering with JSON. That\nenvelope is tenji's discovery and it still works in 2026.\n\ntenji's MIT notice is reproduced in full in [NOTICE](NOTICE), along with a\nprecise account of what was and wasn't derived from it.\n\n## Disclaimer\n\nUnofficial. Not affiliated with, endorsed by, or supported by\nMyFigureCollection.net or Tsuki Board. It scrapes public pages and will break\nwhenever MFC changes its HTML. Item data belongs to MFC and its contributors.\n\nMIT licensed — see [LICENSE](LICENSE).\n\nBuilt by [Sara Kay](https://sarakay.me).\n\nmcp-name: io.github.ssskay/myfigurecollection-api\n",
  "bytes": 13839,
  "sha": "c7279e12a091369d170230e2177be221913e2dab86f2abbdd9e0027975367634",
  "repo_slug": "ssskay/myfigurecollection-api",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ssskay_myfigurecollection_api_b6817026/readme"
}