{
  "markdown": "# Priceminder MCP Server\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-purple)](https://modelcontextprotocol.io)\n[![Website](https://img.shields.io/badge/Web-priceminder.online-green)](https://priceminder.online)\n\n[**中文**](README.zh-CN.md) | [English](README.md)\n\n> **Priceminder** — Real-time Shopee competitor price monitoring, powered by AI agents through the Model Context Protocol (MCP).\n\n🌐 **Sign up free**: [priceminder.online](https://priceminder.online)\n\nMonitor competitor prices across Shopee Southeast Asia (SG, MY, TH, VN, ID, PH). Let your AI agent track, analyze, and alert on price movements — all through natural language.\n\n---\n\n## 📌 Important: Understand the Data Pipeline First\n\nPriceminder's MCP service **does not work standalone**. It depends on competitor price data obtained through paid third-party API data services. Please understand this 3-layer pipeline before using:\n\n```\nInstall Extension → Follow products you want to watch → Backend fetches data via paid APIs → AI Can Query\n```\n\n### ⚠️ Prerequisites\n\n| Step | Action | Details |\n|------|--------|---------|\n| **Required** | ① Install the browser extension | Chrome / Edge / 360 Browser — see [Extension Installation Guide](https://priceminder.online/docs/extensions/) |\n| **Required** | ② Browse Shopee product pages, click \"Monitor Now\" | Only products you manually add to monitoring are accessible via MCP |\n| **Required** | ③ Get your **MCP Key** from extension settings | See [Quick Start](#-quick-start) below |\n| **Optional** | ④ Configure MCP in your AI client | Then you can query prices via natural language |\n\n> 🔑 **Where to get your MCP Key?**\n> The MCP Key is displayed in the **browser extension settings page**. No extension → No Key → No MCP service. The website registration (priceminder.online) is for account management and Pro upgrades — the MCP access credential lives inside the extension.\n\n### 🤖 AI Capability Boundaries\n\nPriceminder's MCP tools can **only query products you've manually added to your monitoring list**. It cannot arbitrarily search all of Shopee.\n\n| AI Can Do ✅ | AI Cannot Do ❌ |\n|---|---|\n| List my monitored products and prices | Search Shopee for products I haven't monitored |\n| View price history and trends of monitored items | Get pricing for any arbitrary ASIN/product ID |\n| Check price drop alerts and push records | Analyze competitor stores I'm not tracking |\n| Add new products to monitor (requires extension scan first) | Auto-discover new competitors |\n| Check crawler engine health status | Modify my account password or settings |\n\n**In short: You tell the system which competitors to watch, MCP lets AI analyze what's been collected.**\n\nFor full capability details, see the [**MCP Tools Overview →**](https://priceminder.online/docs/tools/overview)\n\n---\n\n## 📊 Why Priceminder?\n\n**Real-time, not yesterday.** Most price monitoring tools — including alternative MCP servers — return T-1 (yesterday's cached) data. Priceminder crawls prices **3 times daily**, giving you near-real-time visibility.\n\n| Capability | Alternative MCP Servers | Priceminder |\n|---|---|---|\n| **Data freshness** | T-1 (yesterday) | **T-0 (same-day, 3× daily)** |\n| **Price change detection** | Next day | **Within 4–8 hours** |\n| **Flash sale / 7.7 / 9.9 / 11.11** | Misses intra-day moves | **Catches hourly adjustments** |\n| **Push notifications** | ❌ Query-only | ✅ Feishu/DingTalk/Telegram |\n| **Self-hosted** | ✅ Supported | ✅ Supported |\n\n**In short:** If you're using other tools, you're making decisions on yesterday's data. Priceminder tells you what's happening **right now** — and pushes alerts when competitors move.\n\n---\n\n## 🌟 Features — 8 MCP Tools\n\n| # | Tool | Description | Category |\n|---|---|---|---|\n| 1 | `get_monitor_list` | List all products you're tracking | 🔍 Query |\n| 2 | `get_price_summary` | Batch price summary across all tracked products | 🔍 Query |\n| 3 | `get_price_history` | Price history time-series for a specific product | 🔍 Query |\n| 4 | `get_alerts` | List price drop alerts | 🔍 Query |\n| 5 | `add_monitor` | Add a new product to your monitor list | ⚡ Action |\n| 6 | `update_monitor_status` | Pause or resume monitoring | ⚡ Action |\n| 7 | `get_crawl_health` | Check crawler engine health & stats | 📊 Insight |\n| 8 | `get_monitor_overview` | Dashboard overview of all monitors | 📊 Insight |\n\nSee the full tool documentation here: [**MCP Tools Overview →**](https://priceminder.online/docs/tools/overview)\n\n---\n\n## 🚀 Quick Start\n\n> **Install Extension → Add Products → Get MCP Key → Configure AI Client**\n\nFor visual step-by-step guide with screenshots, see the official docs: [**Quick Start Guide →**](https://priceminder.online/docs/quick-start)\n\n### Step 1: Install the Browser Extension\n\n| Browser | Installation |\n|---|---|\n| **Chrome** | Search \"Priceminder\" on [Chrome Web Store](https://chromewebstore.google.com) |\n| **Edge** | Search \"Priceminder\" on [Edge Add-ons](https://microsoftedge.microsoft.com/addons) |\n| **360 Browser** | Download offline installer from the official website |\n| **Opera** | Opera add-ons store |\n\nSee [**Extension Installation Guide →**](https://priceminder.online/docs/extensions/) for screenshots.\n\n### Step 2: Add Products to Monitor\n\nOpen any Shopee product page (supports SG/MY/TH/ID/TW/PH/VN). A \"**Monitor Now**\" button will appear at the top-right:\n\n1. Click **\"Monitor Now\"** → product added to your monitor list\n2. The system automatically starts collecting price data at your chosen interval\n3. Configure crawl frequency and alert thresholds in the extension settings\n\n> 💡 **You need monitored products first.** Without them, the AI will return empty results when queried. Start by adding at least 5–10 competitor products.\n\n### Step 3: Get Your MCP Key\n\nOpen the browser **extension settings page**. Your MCP Key is displayed in the \"MCP Configuration\" section.\n\n> ⚠️ **The MCP Key is only visible inside the extension settings.** It is not available from the website login.\n\n### Step 4: Configure Your AI Client\n\n**Supported AI Clients (HTTP mode — recommended):**\n\n| Client | How to Configure | Tutorial |\n|---|---|---|\n| Cherry Studio | Settings → MCP → Add HTTP URL | [Guide →](https://priceminder.online/docs/clients/cherry-studio) |\n| OpenClaw | config.yaml → mcp_servers → url | [Guide →](https://priceminder.online/docs/clients/openclaw) |\n| Claude Desktop | claude_desktop_config.json → mcpServers | [Guide →](https://priceminder.online/docs/clients/claude-desktop) |\n| Cursor | Cursor Settings → MCP → Add HTTP URL | [Guide →](https://priceminder.online/docs/clients/cursor) |\n| Cline | Cline MCP Config → Add | [Guide →](https://priceminder.online/docs/clients/cline) |\n| Hermes Agent | config.yaml → mcp_servers | [Guide →](https://priceminder.online/docs/clients/hermes-agent) |\n\nAdd this URL (replace `***` with your MCP Key):\n\n```json\n{\n  \"mcpServers\": {\n    \"sentinel\": {\n      \"url\": \"https://priceminder.online/mcp_server?key=***\"\n    }\n  }\n}\n```\n\nFor detailed client setup guides with screenshots, see: [**Client Setup Guides →**](https://priceminder.online/docs/clients/)\n\n### Step 5: Verify the Connection\n\nTest your setup by asking these questions:\n\n| Your Prompt | Tool Called | Expected Result |\n|---|---|---|\n| \"What am I monitoring?\" | `get_monitor_list` | Your current monitor list |\n| \"How are my competitors' prices?\" | `get_price_summary` | Price summary (current/baseline/high/low/avg) |\n| \"Any new price drop alerts?\" | `get_alerts` | Unread price drop records |\n| \"Is the crawler healthy?\" | `get_crawl_health` | Crawler engine status |\n\n> ✅ If the AI returns your monitoring data, setup is successful.\n>\n> ❌ If results are empty, make sure you've added products to monitor via the extension first.\n\n---\n\n## 💬 Prompt Scenarios\n\nHere are **3 real-world scenarios** you can run — each demonstrates a different use case:\n\n### 1️⃣ Store-Level Price Watch\n\n> *\"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.\"*\n\nYour AI agent will:\n1. Check your monitor list for this store's products\n2. Compare latest crawl prices\n3. Return products that dropped below the threshold\n\n**Best for:** Brand competition — keep tabs on a specific competitor's entire catalog.\n\n### 2️⃣ Flash Sale / Campaign Alert\n\n> *\"Check every 4 hours during the 7.7 sale — alert me if any of my tracked products have a price change of 3% or more. Show only the products that changed.\"*\n\nYour AI agent will:\n1. Call `get_price_summary` to get current vs previous prices\n2. Filter for products with ≥3% movement\n3. Present a clean before/after comparison\n\n**Best for:** Campaign periods — don't wake up to yesterday's data when competitors adjust prices hourly.\n\n### 3️⃣ Price Drop Intelligence\n\n> *\"Show me all price drop alerts from the last 2 days. Which products dropped the most? Highlight any drops over 10%.\"*\n\nYour AI agent will:\n1. Call `get_alerts` for recent notifications\n2. Call `get_price_history` on the biggest movers for context\n3. Rank by drop percentage and highlight critical moves\n\n**Best for:** Buying decisions — spot the deepest discounts.\n\nMore real-world prompt examples: [**Scenarios & Best Practices →**](https://priceminder.online/docs/scenarios)\n\n---\n\n## 🔗 n8n Integration\n\nPriceminder ships with a ready-to-import n8n workflow template.\n\n**File:** [`priceminder-mcp-n8n.json`](priceminder-mcp-n8n.json)\n\n### Workflow\n\n```\nSchedule ─► Get Price Summary ─► Parse Drops ─► Has Drops? ─┬► Telegram Alert\n(4h cron)                                                     ├► Email Alert\n                                                              └► Log (no drops)\n```\n\n### Import\n\n1. Open n8n → **Workflows** → **Import from File**\n2. Select `priceminder-mcp-n8n.json`\n3. Configure credentials:\n   - `SENTINEL_TOKEN` (env var on the n8n host)\n   - Telegram bot token + chat ID (optional)\n   - SMTP credentials (optional)\n4. **Activate** the workflow\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│                  AI Client                          │\n│  (Claude Desktop / Cursor / Cherry Studio / Hermes) │\n└──────────────┬──────────────────────────────────────┘\n               │  MCP Protocol (stdio or HTTP/SSE)\n               ▼\n┌──────────────────────────────────────┐\n│     Priceminder MCP Server           │\n│  ┌────────────────────────────────┐  │\n│  │  Tool Registry (8 tools)      │  │\n│  │  - get_monitor_list           │  │\n│  │  - get_price_summary          │  │\n│  │  - get_price_history          │  │\n│  │  - get_alerts                 │  │\n│  │  - add_monitor                │  │\n│  │  - get_crawl_health           │  │\n│  │  - get_monitor_overview       │  │\n│  └──────────────┬─────────────────┘  │\n│                 │ HTTP + Token Auth\n│  ┌──────────────▼─────────────────┐  │\n│  │  API Client (httpx)           │  │\n│  └──────────────┬─────────────────┘  │\n└─────────────────┼────────────────────┘\n                  │ HTTPS\n┌─────────────────▼────────────────────┐\n│     Priceminder REST API             │\n│  (User Mgmt / Monitor / Price / Alert)│\n└─────────────────┬────────────────────┘\n                  │\n┌─────────────────▼────────────────────┐\n│     PostgreSQL 16                    │\n│  (Price History / Users / Alerts)    │\n└──────────────────────────────────────┘\n```\n\n### Data Flow\n\n```\n① User selects products to monitor via extension\n      │\n      ▼\n② Backend fetches real-time prices via paid third-party API data services → PostgreSQL\n      │\n      ▼\n③ MCP Server reads via API\n      │\n      ▼\n④ AI client queries via MCP protocol\n```\n\n**Key point:** Data flows one way — user selects products → backend fetches via paid APIs → MCP reads. The extension only tells the system which products to watch.\n\n---\n\n## 🔧 Configuration\n\n### Environment Variables\n\n| Variable | Description | Default |\n|---|---|---|\n| `SENTINEL_API_BASE` | Backend API base URL | `https://priceminder.online/shopee` |\n| `SENTINEL_TOKEN` | Your authentication token | **(required)** |\n| `SENTINEL_TIMEOUT` | HTTP request timeout (s) | `30` |\n| `MCP_MODE` | Run mode: `stdio` or `http` | `stdio` |\n| `MCP_HOST` | HTTP server bind address | `127.0.0.1` |\n| `MCP_PORT` | HTTP server port | `8082` |\n| `LOG_LEVEL` | Log level | `INFO` |\n\n---\n\n## 📡 API Reference\n\n### Authentication\n\nAll API calls require these headers:\n\n```bash\nX-Api-Key: sentinel-mvp-2026\nX-Sentinel-Token: YOUR_TOKEN\n```\n\n### Generate MCP Key\n\n```bash\ncurl -X POST https://priceminder.online/shopee/mcp/generate-key \\\n  -H \"X-Api-Key: sentinel-mvp-2026\" \\\n  -H \"X-Sentinel-Token: YOUR_TOKEN\"\n```\n\n---\n\n## 🆓 Free vs Pro\n\n| Feature | Free | Pro |\n|---|---|---|\n| Active monitors | 5 max | Unlimited |\n| Price history | 3 days | 90 days |\n| Price summary | 3 days | 90 days |\n| Call rate | 60/hour | Unlimited |\n| Real-time alerts | — | ✅ |\n| Priority support | — | ✅ |\n\nUpgrade now 👉 [priceminder.online](https://priceminder.online)\n\n---\n\n## 🛠️ Development\n\n```bash\ngit clone https://github.com/haidrau/sentinel-mcp-server.git\ncd sentinel-mcp-server\n\n# Install dev dependencies\npip install -e \".[dev]\"\n\n# Run tests\npython -m pytest tests/\n\n# Start in dev mode\nexport SENTINEL_TOKEN=your-test-token\npython -m sentinel_mcp.server\n```\n\n---\n\n## 📄 License\n\nMIT License — see [LICENSE](LICENSE) for details.\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Feel free to:\n- Open issues for bugs or feature requests\n- Submit PRs for new tools or improvements\n- Ask questions in the discussions\n\n---\n\n## 🌐 Links\n\n- **Website**: [priceminder.online](https://priceminder.online) ← Sign up free\n- **Official Docs**: [priceminder.online/docs](https://priceminder.online/docs/)\n- **Quick Start**: [priceminder.online/docs/quick-start](https://priceminder.online/docs/quick-start)\n- **MCP Tools Overview**: [priceminder.online/docs/tools/overview](https://priceminder.online/docs/tools/overview)\n- **GitHub**: [github.com/haidrau/sentinel-mcp-server](https://github.com/haidrau/sentinel-mcp-server)\n- **Gitee**: [gitee.com/haidrau/sentinel-mcp-server](https://gitee.com/haidrau/sentinel-mcp-server)",
  "bytes": 14363,
  "sha": "5c7faf1d5e20655431764c769c249619337e606b37f06550764efb69f460ed1f",
  "repo_slug": "haidrau/sentinel-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_haidrau_sentinel_mcp_server_bfb7d2bc/readme"
}