Priceminder MCP Server

中文 | English

Priceminder — Same-day Shopee competitor price monitoring, powered by AI agents through the Model Context Protocol (MCP).

🌐 Sign up free: priceminder.online

Monitor competitor prices across Shopee Southeast Asia (SG, MY, TH, VN, ID, PH, BR). Let your AI agent track, analyze, and alert on price movements — all through natural language.

---

📌 Important: Where the Data Comes From — and What's Free

Bottom line first: calling the MCP server is free. MCP and API access are free on every tier, including Free. The Free tier is simply limited by your own watch quota — you can only query the products on your monitoring list.

You don't need to integrate any paid third-party data API yourself. When you click "Monitor Now" on a Shopee product page, the Priceminder backend collects the public product-page price at your plan's cadence (Free: 2×/day, Pro: 4×/day), stores it, and the MCP server reads it back for your AI agent.

Install Extension → Follow products you want to watch → Backend collects & stores → AI Can Query

In short: the MCP server is the open-source access layer; collection and storage are hosted by priceminder.online. All you need is a free account and the steps below.

⚠️ Prerequisites

| Step | Action | Details | |------|--------|---------| | Required | ① Install the browser extension | Chrome / Edge / 360 Browser — see Extension Installation Guide | | Required | ② Browse Shopee product pages, click "Monitor Now" | Only products you manually add to monitoring are accessible via MCP | | Required | ③ Get your credentials from the dashboard | See Quick Start below | | Optional | ④ Configure MCP in your AI client | Then you can query prices via natural language |

🔑 Two credentials — pick the one that matches your mode

| Mode | Credential | Where it goes | |---|---|---| | Hosted HTTP (recommended, nothing to install) | MCP Key (short) | Inside the URL: https://priceminder.online/mcp_server?key=YOUR_MCP_KEY | | Self-hosted stdio (developers, uvx / Docker) | Long API token | SENTINEL_TOKEN environment variable |

Log in to the Priceminder dashboard → Settings → MCP Setup → Generate MCP Key. (The browser extension's settings page shows the same key.) Regenerating the key invalidates the old one immediately. The long API token is your account token, shown in the same settings area.

⚠️ The two are not interchangeable: a short key in SENTINEL_TOKEN, or a long token in the URL, both return 401.

🤖 AI Capability Boundaries

Priceminder's MCP tools can only query products you've manually added to your monitoring list. It cannot arbitrarily search all of Shopee.

| AI Can Do ✅ | AI Cannot Do ❌ | |---|---| | List my monitored products and prices | Search Shopee for products I haven't monitored | | View price history and trends of monitored items | Get pricing for any arbitrary product ID | | Check price drop alerts and push records | Analyze competitor stores I'm not tracking | | Add new products to monitor (requires extension scan first) | Auto-discover new competitors | | Run smart-follow analysis and log pricing decisions | Modify my account password or settings |

In short: You tell the system which competitors to watch, MCP lets AI analyze what's been collected.

For full capability details, see the MCP Tools Overview →

---

💰 Free Usage, Quota & Rate Limits (read this first)

Does MCP / API cost extra?

No. MCP and API are free on all tiers, including Free. The Free tier is naturally limited by your watch quota — you can only query data for the products on your own monitoring list. Source: pricing page · FAQ

Getting the most out of the open-source build

| Your goal | What to do | |---|---| | Use it out of the box | Follow the Free-user flow: register a free account → install the extension and add products → generate an MCP Key (hosted HTTP) or long API token (stdio) → wire it into your AI client. No cost, no credit card | | Modify or extend the code | This repository is MIT licensed — change the transport, add tools, plug in your own scheduler. As long as SENTINEL_API_BASE still points at priceminder.online, you read data within your own account's quota | | Monitor more competitors through the priceminder.online API | Upgrade to Pro: 50 watch slots instead of 5, 4×/day collection instead of 2×/day, no MCP / API quota cap. See pricing |

About the 120 requests/minute limit

Open-source clients share one public API key (the SENTINEL_API_KEY default, sentinel-oss-client-2026), and the backend rate-limits it to 120 requests per minute per user.

This exists to keep the server healthy for everyone — it is not a paywall. Normal conversational use (one question usually triggers 1–3 tool calls) never comes close. What actually limits how many competitors you can watch is your plan's watch quota (Free: 5 products total), not the call rate.

If you genuinely need high-frequency automation (batch sweeps, using MCP as a data source for scripts), upgrading to Pro gives you uncapped API calls.

---

📊 Why Priceminder?

Same-day data, not yesterday's. Most price monitoring tools — including alternative MCP servers — return T-1 (yesterday's cached) data. Priceminder collects on your plan's cadence — Free: twice a day (morning and afternoon), Pro: four times a day — so you act on today's collected price, not an overnight cache.

| Capability | Alternative MCP Servers | Priceminder | |---|---|---| | Data freshness | T-1 (yesterday) | T-0 (same-day; 2×/day on Free, 4×/day on Pro) | | Price change detection | Next day | Same day (within ~6 hours on Pro) | | Flash sale / 7.7 / 9.9 / 11.11 | Misses intra-day moves | Collected at several points during the day + drop alerts | | Push notifications | ❌ Query-only | ✅ Desktop + Feishu (Pro adds Telegram / Slack) | | Smart-follow decision loop | ❌ None | ✅ Analyze → Decide → Review → Stats | | Self-hosted | ✅ Supported | ✅ Supported |

In short: If you're using other tools, you're making decisions on yesterday's data. Priceminder gives you today's collected prices — and pushes alerts when competitors move.

---

🌟 Features — 22 MCP Tools

10 basic tools for querying and monitoring, plus 12 smart-follow tools that close the loop from price movement → competitor response → pricing decision → post-hoc review.

Tier 1 — Query

| # | Tool | Description | API | |---|---|---|---| | 1 | get_monitor_list | List all products you're tracking | GET /monitors | | 2 | get_price_summary | Batch price summary across all tracked products | GET /price/summary | | 3 | get_price_history | Price history time-series for a specific product | GET /price/history | | 4 | get_alerts | List price drop alerts (supports site filter) | GET /alerts |

Tier 2 — Action

| # | Tool | Description | API | |---|---|---|---| | 5 | add_monitor | Add a new product to your monitor list | POST /monitors | | 6 | update_monitor_status | Pause or resume monitoring | PUT /monitors/{id} | | 7 | mark_alert_read | Mark an alert as read | PUT /alerts/{id}/read |

Tier 3 — Insight

| # | Tool | Description | API | |---|---|---|---| | 8 | get_crawl_health | Check crawler engine health & stats | GET /telemetry/summary + /telemetry/site-stats | | 9 | get_monitor_overview | Dashboard overview of all monitors | GET /user/dashboard | | 10 | search_my_products | Search your monitored products | GET /monitors?keyword=xxx |

Tier 4 — Smart Follow (12 tools)

| # | Tool | Description | Example prompt | |---|---|---|---| | 11 | run_smart_follow_analysis | Trigger one smart-follow analysis run (sync batch + status check) | "Run the smart-follow analysis" | | 12 | get_smart_follow_results | Latest analysis results: suggested action, target price, rationale | "What pricing changes do you suggest for my own products?" | | 13 | mark_self_owned | Mark / unmark a product as your own (self-owned) | "Mark this product as mine" | | 14 | map_competitors | Replace the competitor set for a self-owned product | "Set Competitor A as a competitor of my storage box" | | 15 | get_competitor_mapping | View the full self-owned → competitor mapping | "Which competitors are linked to my products?" | | 16 | create_decision | Log a pricing decision | "I'll follow the price down to THB 195" | | 17 | list_decisions | Browse decision history | "Show the decision history for the storage box" | | 18 | review_decision | Review a decision after the fact (free-text outcome + effectiveness enum) | "Review that last price-following decision" | | 19 | adopt_decision | Adopt a suggested decision | "Adopt this suggestion" | | 20 | reject_decision | Reject a suggested decision | "Reject this suggestion" | | 21 | get_smart_follow_stats | Last 30 days decision stats | "What's the adoption and effectiveness rate?" | | 22 | get_algorithm_list | Algorithm list, toggles and parameters | "Which algorithms are in use?" |

Smart-Follow Loop Example

You: Run today's smart-follow analysis
AI : run_smart_follow_analysis() → status=done, 7 rules fired
     get_smart_follow_results() → storage box: follow price to THB 195 (competitor cut 8.5%)
You: Let's follow the price
AI : create_decision(monitor_id=101, action=follow_price, target_price=195) → decision_id=88
     review due in 14 days
You: Adopt that decision
AI : adopt_decision(decision_id=88, actual_price=195)
(14 days later)
You: How did the last price change perform?
AI : get_price_history(...) + comparison → review_decision(decision_id=88,
       review_outcome="sales +12% in 7 days", review_result="effective")
     Overall: get_smart_follow_stats() → 62% adopted, 71% effective

⚠️ Contract notes: the backend /run endpoint executes synchronously (up to 180s) and swallows internal exceptions, so the tool re-checks /run/{id}/status to report the real outcome. get_smart_follow_results reads /latest and does not accept a run id. list_decisions / get_competitor_mapping have limited server-side filtering and pagination — the tools filter and truncate client-side.

See the full tool documentation here: MCP Tools Overview →

---

🚀 Quick Start

Install Extension → Add Products → Get MCP Key (hosted) or Long API Token (stdio) → Configure AI Client

For a visual step-by-step guide with screenshots, see the official docs: Quick Start Guide →

Step 1: Install the Browser Extension

| Browser | Installation | |---|---| | Chrome | Search "Priceminder" on Chrome Web Store | | Edge | Search "Priceminder" on Edge Add-ons | | 360 Browser | Download offline installer from the official website | | Opera | Opera add-ons store |

See Extension Installation Guide → for screenshots.

Step 2: Add Products to Monitor

Open any Sh