myfigurecollection-api

myfigurecollection-api

インストール： pip install myfigurecollection-api · すべての形式とチェックサム

非公式の MyFigureCollection.net API です。Python ライブラリとローカルの MCP サーバーを備えており、エージェントがフィギュアのデータ、コレクション、 リスト、クラブを読み取れます。

MFC には、利用可能な公開 API がありません。公式 API クラブ（#349）では、 8 年間にわたり「API v4 coming soon」と予告され続けています。このパッケージは代わりに 公開 HTML を読み取り、型付きモデルに変換します。

初めての方へ：簡単な概要

MyFigureCollection は、インターネット上で最大規模のアニメフィギュアとグッズのカタログですが、 長年、プログラムからデータを読み取る良い方法がありませんでした。このプロジェクトは、 お使いのコンピューター上でそれを解決します。一度インストールすれば、Claude のような AI アシスタントに MFC の情報を調べてもらえます。「このフィギュアは AmiAmi でいくら？」や 「10 月発売の Chiikawa のアイテムをすべて一覧にして」といった質問ができます。

sequenceDiagram
    participant You
    participant Claude
    participant api as mfc-api, on your computer
    participant MFC as myfigurecollection.net
    You->>Claude: How much is the Alice Carroll figure?
    Claude->>api: get_partner_listings(287)
    api->>MFC: fetch the item's Buy window
    MFC-->>api: HTML
    api-->>Claude: AmiAmi · Available · ¥11,980
    Claude-->>You: AmiAmi has it in stock for ¥11,980

MCP とは？ Model Context Protocol は、AI アシスタントに新しい機能を追加するための標準プラグです。 MCP サーバーは、アシスタントからの呼び出しを許可する、お使いのマシン上の小さなプログラムです。 この MCP サーバーは、アイテム検索からバーコード検索まで、12 種類の MFC 機能をアシスタントに提供します。 追加するには、設定ファイルにスニペットを 1 つ記述します。詳しくはMCP サーバーとして使うをご覧ください。

MFC の公式 API を使わないのはなぜですか？ 公式 API が存在しないためです。サイトの公式 API クラブでは、 2018 年から公開を待ち続けています。

アクセスできるウェブサイトにしないのはなぜですか？ Cloudflare は MFC を保護しており、 アクセスを許可するかどうかを、IP レピュテーションに基づいて判断しています。家庭のコンピューターからの接続は信頼しますが、 サーバーからの接続は信頼しません。そのため、ホストされたバージョンは数日以内にブロックされますが、 お使いのマシンにインストールしたものは動作し続けます。この制約が、設計全体を形作りました。

Python の知識は必要ですか？ インストールにはターミナルで 2 つのコマンドを実行します（下記参照）。 あとはアシスタントに操作を任せられます。

このプロジェクトが生まれた理由（そして、単純な方法ではうまくいかない理由）

MFC は Cloudflare の背後にあり、ユーザーエージェントではなく TLS フィンガープリントに基づいてブロックします。 requests、httpx、aiohttp は、どんなヘッダーを送っても 403 の「Just a moment...」チャレンジを返されます。 そのため、以前の tenji スクレイパーは動作しなくなりました。パーサーが HTML を受け取ることすらできなかったのです。

このパッケージでは、curl_cffi を impersonate="chrome" とともに使い、本物の Chrome のハンドシェイクを再現して 200 を取得します。 この選択は動作に不可欠です。 通常の HTTP クライアントに置き換えると、すべてが動作しなくなります。

これが、ホスト型サービスではなく ローカルツールとして提供する理由でもあります。 Cloudflare は IP レピュテーションを重視するため、データセンターの IP を使うスクレイパーはチャレンジを受け、 共有アドレスを利用する全員に影響を与えます。お使いのマシンで実行してください。

flowchart LR
    A["requests / httpx / aiohttp<br/>(any headers you like)"] -->|"403 Just a moment..."| CF{Cloudflare}
    B["Your browser"] -->|200| CF
    C["mfc-api via curl_cffi<br/>(Chrome TLS handshake)"] -->|200| CF
    CF --> MFC[("myfigurecollection.net")]

インストール

Python 3.10 以降が必要です。このパッケージは PyPI で公開されています。

pip install myfigurecollection-api

Mac では、python3 が Xcode の 3.9 であることが多く、このコードを実行できません。 そのため、使用するインタープリターを明示してください（例：pip3.12）。クローンから作業する場合は、 pip3.12 install -e . を使います。

続いて、正しくインストールされたことを確認します。

mfc-api item 287

mfc-api が見つからない場合は、シェルの python3 の bin ディレクトリが PATH にありません。 python3.12 -c "import sysconfig; print(sysconfig.get_path('scripts'))" でスクリプトの場所を確認し、 その絶対パスを使ってください。

MCP サーバーとして使う

引数を指定せずに mfc-api を実行すると、stdio で MCP サーバーが起動します。次の設定を MCP 設定に追加してください。Claude Desktop の場合は ~/Library/Application Support/Claude/claude_desktop_config.json、Claude Code の場合はプロジェクト内の .mcp.json に追加します。

{
  "mcpServers": {
    "myfigurecollection": {
      "command": "uvx",
      "args": ["myfigurecollection-api"]
    }
  }
}

これには uv のインストールが必要です。初回実行時に uvx が PyPI からパッケージを取得するため、それ以外に設定は必要ありません。

uv がない場合は、インストール済みスクリプトの絶対パスを command に指定してください。例： /Library/Frameworks/Python.framework/Versions/3.12/bin/mfc-api。MCP クライアントは、シェルの Python bin ディレクトリが含まれていない最小限の PATH でサーバーを起動するため、パスは絶対パスでなければなりません。ターミナルでは動作しても、"command": "mfc-api" のように指定すると失敗します。

ツール

ツール	返される内容
get_item(item_id)	アイテムの全情報：カテゴリ、画像、作品、キャラクター、企業、アーティスト、発売情報（日付／版／価格／バーコード）、スケール、高さ、評価、所有者数
search_items(query, page, category_id)	1 ページあたり 50 件のアイテム。ページネーション対応
search_by_barcode(barcode)	JAN／UPC によるアイテム検索。店舗間でアイテムを照合するための結合キー
get_partner_listings(item_id)	アイテムを販売している提携ショップと、在庫状況および価格
get_shop(shop_id)	ホームページ、所在地、配送、評価、レビュー数、アイテム数
search_shops(keywords, page, average_score, partners_only)	ショップディレクトリ。1 ページあたり 10 件
get_profile(username)	登録日、アクセス数、ランク、自己紹介欄、カテゴリごとのコレクション数
get_collection(username, status, page)	1 ページあたり 50 件のアイテム。status は owned、ordered、wished、favorites のいずれかです
get_user_lists(username, page)	ユーザーが公開しているアイテムリスト
get_list(list_id, page)	リストの所有者、説明、タグ、アイテム
get_club(club_id)	説明、スレッド、最近のコメント、スタッフ、メンバー
get_club_members(club_id, page)	メンバー全員の一覧

get_club は新しい機能です。tenji にはありませんでした。

ショップデータについて知っておくべき 2 つのこと

価格が取得できるのは、MFC にバーコードが登録されているアイテムのみです。 get_partner_listings はすべての提携ショップを返しますが、MFC が実際の在庫を確認できるのは、JAN が登録されているアイテムだけです。バーコードのないアイテムでは、32 の提携ショップすべてが価格なしで maybe_available として返されます。これは「未確認」であり、「在庫あり」ではありません。 availability == "available" で絞り込んでください。

search_by_barcode は検索ではなく照会です。 登録済みのバーコードを指定すると、item に完全なアイテム情報が返され、matched: true になります。未登録のバーコードを指定すると matched: false が返されます。実在するバーコードでも MFC に登録されていないものが含まれます。欧米版ではよくあるケースです。

設定

環境変数	デフォルト	意味
MFC_API_RATE_LIMIT	1.0	リクエスト間の秒数
MFC_API_CACHE_TTL	3600	キャッシュの有効期間（秒）。0 にすると無効
MFC_API_CACHE_DIR	~/.cache/mfc-api	キャッシュページの保存先
MFC_API_LOG_LEVEL	WARNING	サーバーログのレベル（ログは stderr に出力）

ライブラリとして使う

from mfc_api import MFCClient, CollectionStatus

with MFCClient() as mfc:
    item = mfc.get_item(287)
    print(item.name)                       # Aria - Alice Carroll - Maa - 1/6 (Toy's Works)
    print(item.releases[0].price)          # 6980.0
    print([c.name for c in item.characters])  # ['Alice Carroll', 'Maa']

    collection = mfc.get_collection("Climbatize", status=CollectionStatus.OWNED)
    print(collection.stats.owned, collection.pagination.total_pages)

    # Walk every page, politely (one request per second)
    for page in mfc.iter_collection("Climbatize", max_pages=3):
        print(page.pagination.current_page, len(page.items))

作品またはキャラクターに関連するすべての情報を取得します（ライブラリと CLI のみ。MCP ツールではありません）。

with MFCClient() as mfc:
    page = mfc.get_entry_items(237138)          # Chiikawa, oldest first, 50 per page
    print(page.pagination.total_items)          # 7247
    item = mfc.get_item(page.items[0].id)
    print(item.picture_large)                   # full-size upload/items/2/ picture

Item.picture は 256px のプレビュー画像、Item.picture_large はアップロードされた元画像です。 transport.get_bytes(url) は同じレートリミッターを使って画像を取得します。429 が発生すると、再試行される代わりに retry_after を持つ MFCRateLimitedError が送出されます。

バーコードを入力して価格を取得：

from mfc_api import MFCClient

with MFCClient() as mfc:
    match = mfc.search_by_barcode("4543341130624")
    if match.matched:
        for listing in mfc.get_partner_listings(match.item.id).available:
            print(listing.shop_name, listing.price, listing.currency)  # AmiAmi 11980.0 JPY

シェルから使う

mfc-api item 287

mfc-api barcode 4543341130624

mfc-api listings 287

mfc-api shops Japan --partners

mfc-api collection Climbatize --status owned --page 2

すべての出力は stdout に JSON 形式で表示され、ログは stderr に出力されます。mfc-api --help で、すべてのサブコマンドを確認できます。mfc-api-cli はエイリアスとして引き続き利用できます。

アイテムページをWayback Machineにアーカイブする

今日読んだ価格や出品情報も、明日には引用できなくなることがあります。ページは更新され、記載内容についてあなたの言葉を信じてもらう必要が出てくるからです。archive=Trueを指定すると、Internet ArchiveのSave Page Nowに公開アイテムページを保存し、その結果をアイテムに添付します。

with MFCClient() as mfc:
    item = mfc.get_item(287, archive=True)
    print(item.releases[0].price, item.archive.wayback_url)
    # 6980.0 https://web.archive.org/web/20260903081500/https://myfigurecollection.net/item/287

1つのフックから、3つの効果が得られます。通常の読み取りの副産物として価格履歴が蓄積され、あなたを信頼していない人でもすべての行を監査でき、データがサイトの存続に左右されなくなります。最後の点は仮定の話ではありません。tenjiは終了し、Mandarakeは2026年9月にアクセス不能になりました。

読み取りが失敗することはありません。 失敗は例外ではなく、1つの行として記録されます。item.archive.statusは、success、already（最近のキャプチャが存在したためArchiveは新たな保存を見送りました。保存という目的は達成されています）、skipped、pending、またはreasonを伴うfailedのいずれかです。Internet Archiveが停止していても、アイテムは取得できます。

人に関する情報は決してアーカイブしません

MFCの大半は人に関する情報です。is_public_item_urlは、クエリ文字列のない/item/<id>を許可リストにしています。そのため、プロフィール、コレクション、ユーザーリスト、クラブの名簿は、リクエストを行う前に拒否されます。

mfc.snapshot("https://myfigurecollection.net/item/287")       # captured
mfc.snapshot("https://myfigurecollection.net/profile/someone")  # skipped, never sent

残す対象だけを列挙する方式では、新しい個人情報のURL形式がすり抜けることはありません。そのため、意図的にブラックリストではなく許可リストを使っています。

オプトイン方式にしている理由

読み取りでは既定でarchive=Falseになっています。アーカイブは、実際に関心のあるアイテムを対象に、独立して意図的に実行する処理です。レイテンシーに敏感なループの中で実行するものではありません。

• 週単位の間隔。 JSON台帳に各URLの最終キャプチャ日時を記録します。過去7日以内にキャプチャされたものは、リクエストを行わずにスキップされます。価格推移を追うには週単位で十分であり、ArchiveとMFCの双方への負荷も軽減できます。送信時にはif_not_archived_within=7dも指定するため、台帳が失われてもArchive側で同じ期間が適用されます。
• 6秒に1件ずつ順番に処理し、実行ごとの上限は50件です。429レスポンスではRetry-Afterを尊重します。

設定	機能
MERCH_ARCHIVE=0	緊急停止スイッチです。プロセス内のすべてのスナップショットを無効にします。関連するmerchクライアント間で共有されるため、1つの変数で一括実行中のアーカイブをすべて停止できます。
MERCH_ARCHIVE_LEDGER	台帳のパスです。関連するクライアント間で共有されるため、1回の処理でURLごとの適切な間隔を一貫して保てます。
MFC_ARCHIVE_LEDGER	このパッケージ専用の台帳のパスです。既定値：<cache dir>/archive-ledger.json。
IA_ACCESS_KEY / IA_SECRET_KEY	Internet ArchiveのS3キーです。archive.org/account/s3.phpから無料で取得できます。macOSでは、Keychainのia-s3-access / ia-s3-secretサービスからも読み取ります。

認証情報がない場合は、修正方法を示す理由とともにstatus="failed"が返されます。クラッシュすることも、何も通知せずに処理を行わないこともありません。

1回の処理につきArchiverを1つ作成し、再利用してください（クライアントが代わりに行います）。こうすることで、レート制限と実行ごとの上限が毎回リセットされず、バッチ全体に適用されます。

サイトへの配慮

• 既定では、プロセス全体で1秒あたり1リクエストに制限されています。
• レスポンスはディスクに1時間キャッシュされるため、エージェントから繰り返し呼び出しても負荷は発生しません。
• 読み取り専用です。ログイン、書き込み、投票の操作はなく、今後も追加する予定はありません。
• Waybackのスナップショットはオプトイン方式で、URLごとに週1回、実行ごとの上限があり、/item/<id>ページだけが対象です。プロフィール、コレクション、リスト、クラブのページは対象外です。

MFCに気づかれるほど大量にスクレイピングすると、CloudflareにIPアドレスへのチャレンジを開始され、誰にとってもサイトの使い勝手が悪くなります。やめましょう。

テスト

python3 -m pytest

既定の実行は完全にオフラインです。パーサーのテストでは、2026-07-30に取得した保存済みHTMLフィクスチャを読み込みます。ライブサイトにアクセスするテストにはliveマークが付いており、既定では選択されません。

python3 -m pytest -m live

MFCのマークアップが変更された可能性がある場合は、これらのテストを実行してください。変更を検知するためのカナリアです。

クレジット

パーサーのアーキテクチャ（ページごとにパーサークラスを用意し、HTMLを受け取ってモデルを返す方式）は、Nate Shoffner（MIT）によるtenjiから移植したものです。セレクターは移植していません。MFCのテンプレートは、tenjiの最終リリース以降に変更されています。tenjiが使用していた2つのエンドポイントは完全に廃止され（itemlists.v4.phpは現在404を返します）、コレクション、プロフィール、リスト、ショップの各ページも、tenjiが想定するものとは異なるマークアップを出力します。

tenjiからそのまま引き継がれたものが1つあります。購入ウィンドウは現在も、commit=loadWindow&window=buyItemを指定した/item/{id}へのフォームPOSTで、JSONを返します。この仕組みはtenjiが発見したもので、2026年現在も動作しています。

tenjiのMITライセンス表記全文はNOTICEに掲載しています。あわせて、tenjiから派生した部分とそうでない部分について、正確に説明しています。

免責事項

非公式のプロジェクトです。MyFigureCollection.netまたはTsuki Boardとの提携、承認、支援はありません。公開ページをスクレイピングするため、MFCがHTMLを変更すると動作しなくなります。アイテムデータの権利はMFCおよびその貢献者に帰属します。

MITライセンスです。詳細はLICENSEをご覧ください。

Sara Kayが開発しました。

mcp-name: io.github.ssskay/myfigurecollection-api