retail-price-tracker-mcp

retail-price-tracker-mcp is an open-source Model Context Protocol (MCP) server for tracking retail product prices. It is designed to work well with Hermes Agent, Claude Desktop, Cursor, and any other MCP client.

The first adapter target is UNIQLO Taiwan. The project is intentionally adapter-based so future stores such as GU, MUJI, momo, or booksellers can be added without rewriting the tracking core.

Status: early scaffold / pre-alpha. The current UNIQLO adapter is conservative: it parses supported URLs and records products, but it does not fabricate live prices when a reliable public API is not available.

Features

• MCP tools for adding, listing, checking, and removing tracked products.

• SQLite persistence for products, price history, and detected events.

• Store adapter architecture.

• UNIQLO Taiwan adapter with search-based current price lookup and safe failure modes.

• Generic static adapter for tests and local demonstrations.

• Hermes skill package with install/config/cron guidance.

• Standard open-source project files: CI, issue templates, PR template, contributing guide, security policy, code of conduct.

Related MCP server: Market Price Finder

MCP tools

Quick start for development

git clone https://github.com/bolin8017/retail-price-tracker-mcp.git
cd retail-price-tracker-mcp
uv venv
uv pip install -e '.[dev]'
uv run pytest
uv run ruff check .

Run the MCP server over stdio:

PRICE_TRACKER_DB="$PWD/tracker.db" uv run retail-price-tracker-mcp

Use the small CLI helper for smoke tests:

uv run retail-price-tracker add 'https://www.uniqlo.com/tw/zh_TW/products/E123456-000' --name 'Demo shirt' --target-price 390
uv run retail-price-tracker list
uv run retail-price-tracker resolve 'AIRism 棉質寬版圓領T恤' --limit 3

Hermes configuration

Add this to ~/.hermes/config.yaml:

mcp_servers:
  retail_price_tracker:
    command: "uvx"
    args: ["retail-price-tracker-mcp"]
    env:
      PRICE_TRACKER_DB: "/home/USER/Documents/Hermes/price-tracker/tracker.db"
    timeout: 120
    connect_timeout: 60

After restarting Hermes, tools will be available with names like:

mcp_retail_price_tracker_add_product
mcp_retail_price_tracker_check_all
mcp_retail_price_tracker_price_history
mcp_retail_price_tracker_resolve_product

See docs/hermes.md and skills/retail-price-tracker/SKILL.md for a full Hermes workflow.

Example Hermes cron prompt

Use the retail price tracker MCP tools to run check_all. If there are price drops, below-target events, sale labels, restocks, or errors needing attention, summarize them for the user in concise Traditional Chinese. If nothing changed, stay silent.

Design principles

1. MCP first: the core should work outside Hermes.

2. Hermes friendly: ship a skill and cron templates for a polished Hermes experience.

3. No fake prices: adapters must return explicit unsupported/unknown results instead of made-up data.

4. Local by default: SQLite on the user's machine; no hosted service required.

5. Adapter-based: stores are plugins around a stable tracking core.

Roadmap

• Harden UNIQLO Taiwan live price fetching with more URL formats and stock detail support.

• Size/color stock tracking.

• resolve_product search/OCR-assisted flow.

• changedetection.io backend integration.

• More adapters: GU, MUJI, momo, booksellers.

• HTTP MCP transport and Docker image.

Security and privacy

Tracked URLs, prices, and shopping preferences are stored locally in SQLite by default. See docs/security.md.

Contributing

Please read CONTRIBUTING.md. Bug reports and adapter contributions are welcome.

License

MIT. See LICENSE.