Priceminder — Shopee Price Monitoring

Priceminder MCP Server

[License: MIT] [Python] [MCP] [Website]

中文 | 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

🔑 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.

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

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.

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

Tier 2 — Action

Tier 3 — Insight

Tier 4 — Smart Follow (12 tools)

Smart-Follow Loop Example

You: Run today's smart-follow analysisAI : 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 priceAI : create_decision(monitor_id=101, action=follow_price, target_price=195) → decision_id=88     review due in 14 daysYou: Adopt that decisionAI : 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

See Extension Installation Guide → for screenshots.

Step 2: Add Products to Monitor

Open any Shopee product page (supports SG/MY/TH/ID/TW/PH/VN). A "Monitor Now" button will appear at the top-right:

1. Click "Monitor Now" → product added to your monitor list
2. The system automatically starts collecting price data at your chosen interval
3. Configure crawl frequency and alert thresholds in the extension settings

💡 You need monitored products first. Without them, the AI will return empty results when queried. Start with a few competitor products — Free covers 5 total, Pro 50.

Step 3: Get Your MCP Key

Log in to the Priceminder dashboard → Settings → MCP Setup → Generate MCP Key.

This short key is for hosted HTTP mode only. If you plan to run the server locally (stdio via uvx or Docker), skip to the self-hosted stdio section — that mode needs your long API token instead.

Then copy the full connection URL shown in the dashboard (the key is already embedded, no extra fields needed):

https://priceminder.online/mcp_server?key=YOUR_MCP_KEY

⚠️ The endpoint is priceminder.online, not mcp.priceminder.online — the latter only serves /health checks.

Step 4: Configure Your AI Client

Supported AI clients (hosted mode — recommended, no local install required):

Generic form (Cherry Studio / OpenClaw / Claude Desktop / Cursor / Cline / Windsurf)

{  "mcpServers": {    "shopee-sentinel": {      "type": "streamable-http",      "url": "https://priceminder.online/mcp_server?key=YOUR_MCP_KEY"    }  }}

WorkBuddy (Tencent)

"Experts · Skills · Connectors" → Connectors tab → Custom Connector (top right) → Configure MCP, paste:

{  "mcpServers": {    "shopee-sentinel": {      "type": "http",      "url": "https://priceminder.online/mcp_server?key=YOUR_MCP_KEY"    }  }}

After saving, you must click "Trust" on the entry — without it the tools will not load on first connection. It's connected once the status shows Connected and 22 tools are listed.

Some builds are strict about the type value: if it isn't recognized, try "type": "streamableHttp" first; if that still fails, remove the whole type line — with url present the client infers HTTP automatically. WorkBuddy supports http (streaming), sse and stdio; Priceminder uses http.

TRAE

Settings → MCP → + Add → Manual / Raw config, paste (omit type):

{  "mcpServers": {    "shopee-sentinel": {      "url": "https://priceminder.online/mcp_server?key=YOUR_MCP_KEY"    }  }}

QwenWork

Extensions → Connectors → + Add, paste (transport type streamable-http):

{  "mcpServers": {    "shopee-sentinel": {      "type": "streamable-http",      "url": "https://priceminder.online/mcp_server?key=YOUR_MCP_KEY"    }  }}

Doubao (ByteDance, desktop client only)

Custom connectors are a form, not pasted JSON: "Plugins · Skills · Partners" → Plugins → + Add → New custom connector:

The web version does not support custom connectors; Priceminder is a public HTTPS service, no local install needed.

For detailed client setup guides with screenshots, see: Client Setup Guides →

Step 5: Verify the Connection

Test your setup by asking these questions:

Your client's tool list should show 22 tools (10 basic + 12 smart follow).

✅ If the AI returns your monitoring data, setup is successful.

❌ If results are empty, make sure you've added products to monitor via the extension first.

Step 6: Troubleshooting

Self-hosted stdio mode (developers)

To run the server locally instead of using the hosted endpoint:

{  "mcpServers": {    "sentinel": {      "command": "uvx",      "args": ["sentinel-mcp-server"],      "env": {        "SENTINEL_API_BASE": "https://priceminder.online/shopee",        "SENTINEL_TOKEN": "your-api-token"      }    }  }}

In stdio mode use the long API token from the dashboard — not the short MCP Key that goes in the hosted URL.

Hermes Agent uses YAML (mcp_servers section of ~/.hermes/config.yaml):

mcp_servers:  sentinel:    command: uvx    args: ["sentinel-mcp-server"]    env:      SENTINEL_API_BASE: "https://priceminder.online/shopee"      SENTINEL_TOKEN: "your-api-token"    enabled: true

💬 Prompt Scenarios

Here are 3 real-world scenarios you can run — each demonstrates a different use case:

1️⃣ Store-Level Price Watch

"Monitor all products from Shopee store 'ABC Official Store' on Shopee SG. If any product drops more than 5% in the last 24 hours, summarize the changes."

Your AI agent will:

1. Check your monitor list for this store's products
2. Compare latest crawl prices
3. Return products that dropped below the threshold

Best for: Brand competition — keep tabs on a specific competitor's entire catalog.

2️⃣ Flash Sale / Campaign Alert

"During the 7.7 sale, list every price change of 3% or more across the products I track. Show only the products that changed."

Your AI agent will:

1. Call get_price_summary to get current vs previous prices
2. Filter for products with ≥3% movement
3. Present a clean before/after comparison

Best for: Campaign periods — don't wake up to yesterday's data when competitors adjust prices several times a day.

3️⃣ Price Drop Intelligence

"Show me all price drop alerts from the last 2 days. Which products dropped the most? Highlight any drops over 10%."

Your AI agent will:

1. Call get_alerts for recent notifications
2. Call get_price_history on the biggest movers for context
3. Rank by drop percentage and highlight critical moves

Best for: Buying decisions — spot the deepest discounts.

4️⃣ Smart-Follow Decision Loop

"Run the smart-follow analysis for my own products, show me the suggestions, and log a decision for the ones I agree with. Then tell me the adoption rate for the last 30 days."

Your AI agent will:

1. Call run_smart_follow_analysis and check the run status
2. Call get_smart_follow_results for suggested actions and target prices
3. Call create_decision for each suggestion you confirm
4. Call get_smart_follow_stats for the 30-day summary

Best for: Operations teams — turn price intelligence into a documented, reviewable pricing workflow.

More real-world prompt examples: Scenarios & Best Practices →

🔗 n8n Integration

Priceminder ships with a ready-to-import n8n workflow template.

File: priceminder-mcp-n8n.json

Workflow

Schedule ─► Get Price Summary ─► Parse Drops ─► Has Drops? ─┬► Telegram Alert(4h cron)                                                     ├► Email Alert                                                              └► Log (no drops)

Import

1. Open n8n → Workflows → Import from File
2. Select priceminder-mcp-n8n.json
3. Configure credentials:
   • SENTINEL_TOKEN (env var on the n8n host)
   • Telegram bot token + chat ID (optional)
   • SMTP credentials (optional)
4. Activate the workflow

🏗️ Architecture

┌─────────────────────────────────────────────────────┐│                  AI Client                          ││  (Claude Desktop / Cursor / Cherry Studio / Hermes) │└──────────────┬──────────────────────────────────────┘               │  MCP Protocol (stdio or HTTP/SSE)               ▼┌──────────────────────────────────────┐│     Priceminder MCP Server           ││  ┌────────────────────────────────┐  ││  │  Tool Registry (22 tools)      │  ││  │  Tier 1–3: query/action/insight│  ││  │  Tier 4: smart follow          │  ││  └──────────────┬─────────────────┘  ││                 │ HTTP + Token Auth│  ┌──────────────▼─────────────────┐  ││  │  API Client (httpx)           │  ││  └──────────────┬─────────────────┘  │└─────────────────┼────────────────────┘                  │ HTTPS┌─────────────────▼────────────────────┐│     Priceminder REST API             ││  (User / Monitor / Price / Alert /   ││   Telemetry / Smart-Follow)          │└─────────────────┬────────────────────┘                  │┌─────────────────▼────────────────────┐│     PostgreSQL 16                    ││  (Price History / Users / Alerts /   ││   Decisions / Competitor Maps)       │└──────────────────────────────────────┘

Data Flow

① User selects products to monitor via extension      │      ▼② Backend collects public product-page prices at your plan's cadence → PostgreSQL      │      ▼③ MCP Server reads via API      │      ▼④ AI client queries via MCP protocol

Key point: Data flows one way — user selects products → backend collects on the hosted side → MCP reads. The extension only tells the system which products to watch; collection and storage happen in the cloud, so you don't wire up a data source yourself and you don't pay extra (the Free tier is bounded by your watch quota — see pricing).

🔧 Configuration

Environment Variables

📡 API Reference

Authentication

All backend API calls require these headers:

X-Api-Key: YOUR_API_KEYX-Sentinel-Token: YOUR_TOKEN

🆓 Free vs Pro

MCP and API are free on all tiers — the difference between Free and Pro is watch quota, collection frequency and data retention, not whether you can call the server.

Full entitlements and current pricing: priceminder.online/en/pricing →

Want the priceminder.online API to watch many more competitors at 4×/day? Upgrade to Pro 👉 pricing

🛠️ Development

git clone https://github.com/haidrau/sentinel-mcp-server.gitcd sentinel-mcp-server
# Install dev dependenciespip install -e ".[dev]"
# Verify all 22 tools are registeredpython -c "import asyncio, sentinel_mcp.server as s; print(len(asyncio.run(s.mcp.list_tools())))"
# Run testspython -m pytest tests/
# Start in dev modeexport SENTINEL_TOKEN=your-test-tokenpython -m sentinel_mcp.server

📄 License

MIT License — see LICENSE for details.

🤝 Contributing

Contributions are welcome! Feel free to:

• Open issues for bugs or feature requests
• Submit PRs for new tools or improvements
• Ask questions in the discussions

💌 Contact

Questions, bug reports, feature requests or partnership inquiries — all welcome. We reply within 24 hours on business days.

Email: [email protected]

🌐 Links

• Website: priceminder.online ← Sign up free
• Pricing & plans: priceminder.online/en/pricing
• Official Docs: priceminder.online/docs
• Quick Start: priceminder.online/docs/quick-start
• MCP Tools Overview: priceminder.online/docs/tools/overview
• GitHub: github.com/haidrau/sentinel-mcp-server
• Gitee: gitee.com/haidrau/sentinel-mcp-server