canyon-mcp

Find the bike. Close the tabs. Skip the spreadsheet.

A read-only CLI and Model Context Protocol (MCP) server for Canyon's public bicycle catalog. Search models, compare specifications, inspect sizes and availability, or export a shortlist. No account or checkout flow required.

What you can do

The project reads public listing, product, and sitemap pages. It does not sign in, add items to a cart, or place orders. A bike may still sell out between a query and your next ride.

Related MCP server: ReviewOracle

Quick start

Install Bun 1.3 or newer, then clone this repository:

git clone https://github.com/jb381/canyon-mcp.git
cd canyon-mcp
bun install --frozen-lockfile
bun run dev:cli search grail --limit 5

Pick a model ID from the results to see sizes, colors, specifications, and variant availability:

bun run dev:cli product 4509

The default store is en-de. Use --locale de-de or another Canyon language-country locale to change it. Run bun run dev:cli locales to see locales found in Canyon's sitemap.

A few useful routes

# Find listed medium Grail models with stock in the selected store
bun run dev:cli search grail --size M --in-stock

# Compare models and get machine-readable output
bun run dev:cli compare 4509 4508
bun run dev:cli search grail --json

# Export a shortlist, or check a model periodically
bun run dev:cli export --world gravel --format csv --output gravel.csv
bun run dev:cli watch 4509 --size M --interval 300

watch prints an initial snapshot and changes in variants, price, or availability. Stop it with Ctrl-C. Its minimum polling interval is 60 seconds. Run bun run dev:cli --help for every command and option.

Connect an MCP client

Build once, then point your MCP client at the compiled server using an absolute path:

bun run build
which bun

{
  "mcpServers": {
    "canyon": {
      "command": "/absolute/path/to/bun",
      "args": ["/absolute/path/to/canyon-mcp/dist/mcp.js"]
    }
  }
}

Replace both example paths with paths on your machine. Some MCP clients can resolve bun directly, in which case "command": "bun" also works. The server uses stdio; its normal output is reserved for MCP messages.

Ask your client to search for a gravel bike in size M, compare two model IDs, or show the variants for a product URL. The four tools return human-readable text and structured data.

Data, limits, and courtesy

• Search reads at most the first 200 listing tiles per request. It is a shortlist tool, not a complete catalog mirror. total is best effort and may differ from Canyon's full catalog count.

• Search tiles can omit or leave availability unknown. Use product or get_bike to inspect variant-level stock. --in-stock filters the listing, but a final product-page check is still sensible.

• Results include fetchedAt and stale. stale: true means a temporary request failure caused a fallback to older cached data.

• Successful responses are cached in ~/.cache/canyon-mcp/cache.sqlite. By default, requests are spaced at least two seconds apart. Set CANYON_CACHE_PATH to change the cache location, CANYON_MIN_INTERVAL_MS to change the delay, and CANYON_USER_AGENT to identify a shared deployment.

• The HTTP client accepts only https://www.canyon.com pages and blocks /on/demandware.store/ endpoints. Please keep usage modest and respect Canyon's robots.txt and website terms.

Develop

bun run check
bun run test
bun run build
bun pm pack --dry-run

Tests use local fixtures. bun run test:live makes a fresh request to Canyon and should be run sparingly. See CONTRIBUTING.md for the small contribution checklist.

License

MIT. Canyon and its product names are trademarks of their respective owners.