Getting started

ASINRating is a free, read-only MCP data service that mirrors Amazon US public Best Sellers ranks (amazon.com; US market only) and cross-verifies product facts from public listings. Fact-only, neutral, no sponsored entries, no promotional tags.

Endpoint

• URL: https://asinrating.com/mcp
• Protocol: Model Context Protocol (streamable HTTP)
• Authentication: none — no API key, no sign-up
• Methods: initialize, tools/list, tools/call
• Rate limits: usage may be rate-limited to protect service stability

Quick start

1. Initialize the session:

{
  "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": "2025-03-26",
    "capabilities": {},
    "clientInfo": {"name": "your-agent", "version": "1.0"}
  }
}

2. Call a tool:

{
  "jsonrpc": "2.0", "id": 2, "method": "tools/call",
  "params": {
    "name": "list_categories",
    "arguments": {}
  }
}

For MCP-compatible assistants (ChatGPT, Claude, Muse, Grok), simply add https://asinrating.com/mcp as a connector — no manual JSON-RPC required.

Standard discovery chain

The server implements the full standard MCP discovery flow: initialize → tools/list → tools/call. tools/list returns the complete catalog of all eleven tools with their input schemas — always discover tools from the server rather than assuming a fixed list, and send notifications/initialized after initialize if your client requires it.

Suggested flow

1. Discover — list_categories to enumerate categories and subcategories.

2. Orient — get_category_brief for a structured market overview of a category.

3. Filter / Compare — search_products to shortlist candidates; compare_products for side-by-side facts.

4. Verify — get_product for the full profile including three-source facts check and red-flag signals; scrap_page when the freshest price or stock is required.

5. Transact — open the plain product_url (no promotional tags) on Amazon.

Response conventions

Every tool response carries a notes block:

• Quantitative fields return the string insufficient_sample when the underlying sample is too small — a fact, not an error.
• Partial claims under manual review surface in data_limitations, never silently.
• Red-flag signals are confidence-layered: only high-confidence cases are marked avoid_strong.
• Errors return {"error": "..."} with a human-readable message; unknown category_id responses include a hint.

Web pages vs API

These web pages show only the category structure. Product-level Top-100 lists and all product data are served exclusively through the MCP API.

Tool catalog

Data principles

• Facts only: no composite scores, no verdicts, no recommendations.
• Transparent freshness: every response exposes its data timestamp and staleness.
• No commercial bias: product links are plain Amazon pages; the service derives no commercial benefit from links.

Full machine-readable guides: agents.md and llms.txt.

Maintenance

ASINRating is maintained by Bobbi Tseng, reachable at support@asinrating.com. Security reports: support@asinrating.com, admin@asinrating.com.

list_categories

List the top-level product categories and their subcategories covered by this service. Subcategories are enumerable: each carries a human-readable name and a stable subcategory_id you can pass directly to get_top100.

When to use: always call this first — every category-scoped tool takes a category_id or subcategory_id returned here.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 3, "method": "tools/call",
  "params": {"name": "list_categories", "arguments": {}}
}

Response shape

{
  "categories": [
    {
      "category_id": "all-departments",
      "name": "All Departments",
      "subcategories": [
        {"subcategory_id": "7073960011", "name": "Portable Power Banks"},
        {"subcategory_id": "...", "name": "On-Dash Cameras"}
      ],
      "coverage_status": "covered"
    }
  ],
  "notes": {"confidence": "...", "data_as_of": "...", "...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

Subcategory names mirror Amazon's public category tree. Use get_top100 with either the parent category_id (whole department) or a specific subcategory_id (single list).

Related tools

• get_top100 — rankings for a category or a single subcategory
• get_category_brief — structured market brief for a top-level category

get_category_brief

Get a structured market brief for a top-level category: market overview metrics, consideration factors, gotchas, scene needs, keywords, and a candidate pool of ASINs.

When to use: to orient within a category before picking individual products.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 5, "method": "tools/call",
  "params": {
    "name": "get_category_brief",
    "arguments": {"category_id": "all-departments"}
  }
}

Response shape

{
  "category": {"category_id": "...", "name": "..."},
  "market_overview": {
    "subcategories": 9,
    "heat_score": 72.4,
    "brand_count": 148.2,
    "seller_count": 210.9,
    "monopoly_index": 0.31,
    "top100_coverage": 0.87,
    "congestion_score": 55.0
  },
  "considering_factors": ["..."],
  "gotchas": [{"factor": "...", "source": "multi-source cross-verified review corpus"}],
  "common_questions": [],
  "common_questions_available": false,
  "needs": ["..."],
  "keywords": ["..."],
  "candidate_pool": {"sample_asins": ["B01MTB55WH", "..."]},
  "notes": {"sample_size": 1200, "...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

> The category brief is derived from a sample of products. CCF/Gotchas are inductive findings, not exhaustive; mention rates and sentiment distributions are statistical representations, not recommendations. See sample_size; quantitative fields return insufficient_sample when the sample is insufficient.

Related tools

• get_top100 — the ranked list behind the category
• get_product — verify candidate ASINs individually

get_top100

Get the Best Sellers Rank list (rank 1..N) for either a whole top-level category or a single subcategory. Ranking is an objective representation of Amazon's official best-seller list, presented without evaluation.

When to use: after list_categories, to pull the ranked list that anchors category research.

Parameters

Provide exactly one of the two. Rankings are per subcategory list (rank 1..N).

Example call

{
  "jsonrpc": "2.0", "id": 4, "method": "tools/call",
  "params": {
    "name": "get_top100",
    "arguments": {"subcategory_id": "7073960011"}
  }
}

Response shape

{
  "category": {"category_id": "...", "name": "..."},
  "list_size": 100,
  "top100": [
    {
      "rank": 1,
      "bsr_subcategory_rank": 1,
      "subcategory_id": "7073960011",
      "asin": "B01MTB55WH",
      "brand": "Anker",
      "title": "Portable Charger ...",
      "rating": 4.6,
      "review_count": 25000,
      "rating_distribution": {"five_star": 78, "four_star": 14, "...": "..."},
      "price": 29.99,
      "price_as_of": "2026-11-04T08:12:00Z",
      "product_url": "https://www.amazon.com/dp/B01MTB55WH",
      "buyer_signal": null
    }
  ],
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

> BSR ranking is an objective representation of Amazon's official best-seller list, presented without evaluation. Rankings update over time; see data_as_of for the data timestamp. Prices are snapshots (see price_as_of); for a real-time quote call scrap_page or open product_url. For side-by-side comparison, call compare_products with 2-5 ASINs.

Related tools

• get_product — full profile for any ASIN in the list
• compare_products — side-by-side across dimensions
• scrap_page — real-time price/stock snapshot

get_product

Get a product's full profile: specifications, the complete listing description, ratings, price, trend, dimension scores and percentiles, three-source facts check, red-flag signals, and sentiment.

When to use: to verify a candidate ASIN in depth before recommending or comparing it.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 6, "method": "tools/call",
  "params": {
    "name": "get_product",
    "arguments": {"asin": "B01MTB55WH"}
  }
}

Response shape

{
  "profile": {
    "asin": "B01MTB55WH",
    "title": "Portable Charger ...",
    "brand": "Anker",
    "specifications": {"...": "..."},
    "feature_bullets": ["..."],
    "full_description": "Complete product description paragraph from the listing (null when the source listing has no description)",
    "categories": ["..."],
    "product_url": "https://www.amazon.com/dp/B01MTB55WH",
    "media": {"videos_count": 2, "images_count": 18}
  },
  "price": {
    "price_current": 29.99,
    "currency": "USD",
    "hist_180d_min": 25.99,
    "hist_180d_max": 35.99,
    "price_as_of": "2026-11-04T08:12:00Z"
  },
  "ratings": {"rating": 4.6, "review_count": 25000, "rating_distribution": {"...": "..."}},
  "competitiveness": {"bsr_leaf_rank": 1, "bought_past_month": 9000, "...": "..."},
  "seller": {"buybox_seller": "...", "fba": true, "is_prime": true, "...": "..."},
  "facts_check": [
    {"claim_id": "...", "claim_text": "...",
     "user_reviews": "corroborated", "social_ugc": "unmentioned_in_reviews",
     "seller_self": "consistent", "needs_manual_review": false}
  ],
  "red_flags": {"verdict": "...", "confidence": "...", "buyer_signal": null},
  "sentiment": {"overall_polarity": "positive", "themes": ["..."], "sample_size": 320},
  "data_limitations": [],
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

Verdict vocabulary

• corroborated / contradicted — the source confirms or contradicts the claim.
• unmentioned_in_reviews — data sparsity, meaning "not mentioned in reviews", not "refuted".
• consistent / inconsistent — internal consistency of the seller's own copy.

Tool note

> Facts check presents three sources independently: user reviews and social UGC may show unmentioned_in_reviews due to data sparsity (meaning "not mentioned in reviews", not "refuted"); seller_self verifies internal consistency of the seller's own copy. Red-flag signals are layered by confidence — only high-confidence suspicious cases are marked avoid_strong. Evaluate each claim's credibility yourself; this tool draws no conclusion. Prices are snapshots (see price_as_of in the price block); for a real-time quote call scrap_page or open product_url. For side-by-side comparison, call compare_products with 2-5 ASINs.

Related tools

• compare_products — side-by-side across dimensions
• scrap_page — real-time price/stock snapshot
• request — same payload with field filtering

request

Fetch structured data by URL or ASIN with optional field filters. Same payload as get_product, but accepts an Amazon product URL directly and lets you request only the fields you need.

When to use: when you have a product URL instead of an ASIN, or want a trimmed payload.

Parameters

Available fields

profile, price, trend, ratings, competitiveness, seller, facts_check, red_flags, sentiment

Example call

{
  "jsonrpc": "2.0", "id": 9, "method": "tools/call",
  "params": {
    "name": "request",
    "arguments": {
      "url": "https://www.amazon.com/dp/B01MTB55WH",
      "fields": ["price", "ratings"]
    }
  }
}

Response shape

{
  "price": {"price_current": 29.99, "currency": "USD", "price_as_of": "2026-11-04T08:12:00Z"},
  "ratings": {"rating": 4.6, "review_count": 25000, "rating_distribution": {"...": "..."}},
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

• Unknown fields values return an error listing the available keys.
• Quantitative fields return insufficient_sample when the underlying sample is too small.

Tool note

> Returns raw data by structured fields; see schema for field definitions. Quantitative fields return insufficient_sample when the sample is insufficient.

Related tools

• get_product — full payload, ASIN input
• get_price — price-only shortcut

get_brand

Get a brand's full profile from the brand registry: tier, product count, cumulative review count, rating breakdown, seller positive percentage, subcategory monopoly HHI, 90-day trend, and ratings gained over 30/90 days. Pass a brand_name for an exact match, or a partial name to receive candidate matches.

When to use: researching a brand's market footprint and concentration; pass an exact brand_name or a partial name to receive candidate matches.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 12, "method": "tools/call",
  "params": {
    "name": "get_brand",
    "arguments": {"brand_name": "Samsung"}
  }
}

Response shape

{
  "brand": {
    "brand_name": "Samsung",
    "category_ids": ["Electronics"],
    "product_count": 12,
    "variant_count": 30,
    "review_count_total": 120000,
    "avg_rating": 4.5,
    "rating_breakdown": {"five_pct": 74.0, "four_pct": 10.8, "three_pct": 6.0, "two_pct": 3.0, "one_pct": 6.6},
    "seller_positive_pct": 0.92,
    "buybox_share_30d": 0.85,
    "monopoly_hhi": 0.12,
    "ratings_gained_30d": null,
    "ratings_gained_90d": null,
    "trend_90d": null,
    "tier": "head",
    "amazon_buybox_share": 0.85,
    "first_seen_at": "2026-11-04T00:00:00Z",
    "updated_at": "2026-11-04T00:00:00Z",
    "avg_price": 299.99,
    "max_bought_past_month": 5000,
    "best_bsr": 1234,
    "price_bucket": ">$100"
  },
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

> Brand fields are objective registry facts: tier, counts, rating breakdowns, and concentration measures. No evaluation or recommendation is attached.

Related tools

• get_product — product-level profile with brand tier and social presence
• list_categories — categories a brand may appear in

search_products

Search for candidate products matching a query, each with a data-maturity tier. Supports sorting and price/rating filters.

When to use: to shortlist candidates by keyword before deeper verification.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": {
    "name": "search_products",
    "arguments": {"query": "power bank", "sort": "rating_desc", "max_price": 40}
  }
}

Response shape

{
  "results": [
    {
      "asin": "B01MTB55WH",
      "brand": "Anker",
      "title": "Portable Charger ...",
      "data_tier": "top",
      "price": 29.99,
      "price_as_of": "2026-11-04T08:12:00Z",
      "rating": 4.6,
      "review_count": 25000,
      "rating_distribution": {"five_star": 78, "...": "..."},
      "product_url": "https://www.amazon.com/dp/B01MTB55WH"
    }
  ],
  "notes": {"...": "..."}
}

*(abbreviated for readability; result limit 100)*

Field notes

Tool note

> Sort with sort (price_asc | price_desc | rating_desc | review_count_desc); filter with min_price, max_price, min_rating (USD / 0-5 stars). Results include product_url and price_as_of; prices are snapshots — for a real-time quote call scrap_page. For side-by-side comparison, call compare_products with 2-5 ASINs.

Related tools

• compare_products — side-by-side for the shortlist
• get_product — deep verification per ASIN

compare_products

Compare two to five products side-by-side across dimensions. The comparison is a dimension-by-dimension presentation with no ranking of better or worse — judgment is left to you.

When to use: after shortlisting, to put the candidates' facts next to each other.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 8, "method": "tools/call",
  "params": {
    "name": "compare_products",
    "arguments": {"asins": ["B01MTB55WH", "B07QK2SPP7"]}
  }
}

Response shape

{
  "products": ["B01MTB55WH", "B07QK2SPP7"],
  "dimensions": {
    "specs": {"B01MTB55WH": {"...": "..."}, "B07QK2SPP7": {"...": "..."}},
    "rating": {"B01MTB55WH": 4.6, "B07QK2SPP7": 4.4},
    "review_count": {"B01MTB55WH": 25000, "B07QK2SPP7": 12000},
    "price": {"B01MTB55WH": 29.99, "B07QK2SPP7": 25.99},
    "competitiveness": {"B01MTB55WH": {"...": "..."}, "B07QK2SPP7": {"...": "..."}},
    "facts_check": {"B01MTB55WH": {"claims": 12, "social_ugc_corroborated": 5, "...": "..."}}
  },
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

> The comparison is a side-by-side, dimension-by-dimension presentation with no ranking of better or worse. Judge for yourself.

Related tools

• get_product — full profile for each compared ASIN
• scrap_page — freshest price for the finalists

get_price

Get a product's latest stored price and product-page link.

When to use: quick price check from the stored snapshot; call scrap_page if you need a real-time quote.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 10, "method": "tools/call",
  "params": {
    "name": "get_price",
    "arguments": {"asin": "B01MTB55WH"}
  }
}

Response shape

{
  "asin": "B01MTB55WH",
  "price_current": 29.99,
  "price_currency": "USD",
  "product_url": "https://www.amazon.com/dp/B01MTB55WH",
  "price_as_of": "2026-11-04T08:12:00Z",
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

> Price is as of query time (see price_as_of). The product link is an Amazon product-page URL with no promotional tag; this tool derives no commercial benefit from the link.

Related tools

• scrap_page — real-time price and stock
• get_product — full price block with 180-day history

get_price_change

Get a product's 180-day price change summary from recorded history: current price, 180-day low/high/average, sample count, and where the current price sits among its own recorded observations.

When to use: answering "is now a good time to buy" style questions from historical data. This is a stored snapshot — call scrap_page for a real-time quote.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 11, "method": "tools/call",
  "params": {
    "name": "get_price_change",
    "arguments": {"asin": "B01MTB55WH"}
  }
}

Response shape

{
  "asin": "B01MTB55WH",
  "price_current": 29.99,
  "price_currency": "USD",
  "low_180d": 24.99,
  "high_180d": 39.99,
  "avg_180d": 32.45,
  "sample_count_180d": 6,
  "position_in_180d_range_pct": 16.7,
  "current_vs_avg_180d_pct": -7.6,
  "current_vs_low_180d_pct": 20.0,
  "current_vs_high_180d_pct": -25.0,
  "price_as_of": "2026-11-04T08:12:00Z",
  "product_url": "https://www.amazon.com/dp/B01MTB55WH",
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

Tool note

> Statistics come from the recorded pipeline history (see price_as_of), presented without evaluation. This tool draws no conclusion on whether to buy; interpret the numbers yourself.

Related tools

• get_price — latest stored price
• scrap_page — real-time price and stock
• get_product — full price block with the same 180-day history

scrap_page

Scrape a product page in real time for the latest price, stock, Buy Box seller, rating, and review count. This is the only tool that returns a live snapshot rather than stored data.

When to use: only when the freshest price or stock is required — real-time scraping is slower than stored-data tools.

Parameters

Example call

{
  "jsonrpc": "2.0", "id": 11, "method": "tools/call",
  "params": {
    "name": "scrap_page",
    "arguments": {"asin": "B01MTB55WH"}
  }
}

Response shape

{
  "asin": "B01MTB55WH",
  "price": 29.99,
  "currency": "USD",
  "stock": "In Stock",
  "buybox_seller": "Amazon.com",
  "buybox_seller_note": null,
  "rating": 4.6,
  "review_count": 25000,
  "product_url": "https://www.amazon.com/dp/B01MTB55WH",
  "data_as_of": "2026-11-04T09:30:00Z",
  "notes": {"...": "..."}
}

*(abbreviated for readability)*

Field notes

• Results are cached for 10 minutes per ASIN; repeated calls within the window return the same snapshot.
• A failed scrape returns {"error": "scrape failed: <type>"} — never a fabricated value.

Tool note

> This is a real-time scrape snapshot; see data_as_of for the data timestamp. Real-time scraping is slower — call only when the latest price or stock is required.

Related tools

• get_price — stored price, faster
• get_product — full profile from stored data