watchcharts-mcp

MCP server for watchcharts.com — luxury watch market prices and trends, exposed as tools for Claude and other MCP clients.

How it works

WatchCharts is protected by a Cloudflare JS challenge that blocks plain HTTP clients and vanilla headless browsers. This server uses patchright (stealth-patched Playwright) driving your system Google Chrome in headful mode, with the window parked off-screen. API calls run inside the page via fetch(), reusing the browser's cookies, TLS fingerprint and CSRF token.

The private REST API was reverse-engineered from HAR captures of the /market screener and the marketplace:

filters is base64-encoded JSON: key -1 = price cap, keys -100…-105 = time period (1m…5y) with minimum trend %. Brand filtering uses the brandId query param. Each subdomain has its own CSRF token (read from #csrfToken[data-token]), but the Chrome context/cookies are shared.

Related MCP server: mcp-financex

Requirements

• macOS/Linux/Windows with Google Chrome installed

• Python ≥ 3.12, uv

Tools

watch_id from search_watches composes with get_price_history and search_ebay. variation_id from get_watch_info narrows get_price_history, get_watch_sales, and get_listings_history to a single reference/dial.

Appraisal (captcha-gated, driven via the real form)

appraise_watch is the equivalent of the paid API's appraisal.

Usage:

appraise_watch(
    query="Rolex Daytona 116503",   # name or reference
    condition="Pre-owned",          # or "New" / "Unworn"
    accessory="box and papers",     # or "box only" / "watch only"
    region="Europe",                # or "North America" / "Asia"
)
# → {"watch": "Rolex Cosmograph Daytona 116503",
#    "estimated_value": "€17,671",
#    "condition": "Pre-owned", "accessory": "Watch with original box and papers",
#    "region": "Europe", "summary": "..."}

condition / accessory / region are matched by substring against the form's dropdown labels, so partial words work. The response echoes back the label actually matched. The inputs move the number — e.g. new + watch-only + North America → €18,058.

Why it's different from the other tools. Its submit endpoint is protected by a per-request captcha token that only the page's own JS can mint. There is no token stored anywhere in this code — each call drives the real /appraisal form (type reference → pick the match → set the dropdowns → submit), and the browser mints a fresh token at submit time. That's why "will it still work tomorrow?" is a yes: nothing is cached that can expire. The only prerequisites are the same as every other tool — Chrome installed and Cloudflare passing.

What can break it. Because it's UI-driven, it depends on the form's DOM structure. If WatchCharts redesigns the /appraisal form, update APPRAISAL_SELECTORS in client.py — that dict is the single place all the selectors live. The parsing of the rendered result is separate (_parse_appraisal_report) and covered by an offline fixture test, so a wording change in the report surfaces as a test failure. It's ~10-15s per call (a real browser flow) and more fragile than the JSON-backed tools — use it for one-off valuations, not bulk lookups.

Install

git clone https://github.com/NiccoloSalvini/watchcharts-mcp
cd watchcharts-mcp
uv sync

Claude Code

claude mcp add watchcharts -- uv run --directory /path/to/watchcharts-mcp watchcharts-mcp

Claude Desktop

{
  "mcpServers": {
    "watchcharts": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/watchcharts-mcp", "watchcharts-mcp"]
    }
  }
}

Development

uv run pytest        # offline parser tests against fixtures in tests/fixtures

Parsers are pinned by fixture tests: if WatchCharts redesigns its markup, tests fail instead of tools returning silently empty data.

Notes

• First tool call launches Chrome and solves the Cloudflare challenge (~15–30 s); later calls are fast. The Chrome profile is cached in ~/.cache/watchcharts-mcp/chrome-profile so subsequent launches reuse cf_clearance.

• Free-tier data: results are capped by WatchCharts (2000 rows) and some columns require a Professional subscription.

• For personal/research use. Respect WatchCharts' terms of service.