Shoptera Product Intelligence

Search product catalogs across thousands of Central European e-shops. Semantic search, keyword matching, GTIN/EAN lookup — via REST API or MCP.

~2,500 e-shops | ~8.5M products | 7 countries (CZ, SK, PL, HU, RO, DE, AT)

Live stats: GET /stats/global

Tools

Three MCP tools are available. All are read-only and require no authentication.

search_products — Semantic Search

Natural language search using vector embeddings. Understands intent, synonyms, and context across Czech, Slovak, German, Polish, Hungarian, Romanian, and English.

When to use: Open-ended queries, gift ideas, category browsing, intent-based search.

Returns: Products ranked by semantic relevance score (0-1). Includes title, description, price, currency, brand, category, gtin, image_url, product_url, availability, eshop info, and cart_action.

search_products_by_text — Keyword Search

Exact keyword matching in product titles. Deterministic results, faster than semantic search.

When to use: Known product names, model numbers, brand + product combinations.

Returns: Products matching all keywords. Same fields as semantic search (without score).

lookup_by_gtin — GTIN/EAN Barcode Lookup

Exact barcode match. Finds all e-shops selling a product by GTIN/EAN/UPC.

When to use: Price comparison by barcode, product identification.

Returns: All products matching the barcode. Same fields as keyword search.

Tool Selection Guide

User has a barcode number?  -->  lookup_by_gtin
User knows the exact product name?  -->  search_products_by_text
User describes what they want?  -->  search_products

Installation

No authentication required. MCP endpoint: https://shoptera.ai/mcp/ (streamable HTTP, stateless)

Claude Code

claude mcp add --transport http shoptera https://shoptera.ai/mcp/

Cursor

Add to Cursor Settings > Features > MCP > Add New MCP Server, or edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "shoptera": { "url": "https://shoptera.ai/mcp/" }
  }
}

Windsurf

Add via Cascade > MCP Servers > Add Server, or edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "shoptera": { "url": "https://shoptera.ai/mcp/" }
  }
}

VS Code (Copilot / Continue)

Edit .vscode/mcp.json in your workspace:

{
  "mcpServers": {
    "shoptera": { "url": "https://shoptera.ai/mcp/" }
  }
}

Any tool (universal installer)

npx add-mcp https://shoptera.ai/mcp/ -n shoptera -g -y

All Platforms

Usage

Semantic search — natural language, understands intent

curl "https://shoptera.ai/api/v1/search?q=dárek+pro+zahradníka+do+500+Kč&max_price=500¤cy=CZK&origin_country=CZ"

Keyword search — exact title matching, fast

curl "https://shoptera.ai/api/v1/search/text?title=Nike+Air+Max+90&brand=Nike"

GTIN/EAN lookup — find e-shops by barcode

curl "https://shoptera.ai/api/v1/search/gtin/5901234123457"

Saving tokens — return only the fields you need

curl "https://shoptera.ai/api/v1/search?q=boty&limit=5&fields=title,price,product_url,cart_action"

Cart actions

Every product includes a cart_action object:

• method: "GET" — navigate to url to add the product to cart automatically

• method: "browser_click" — navigate to url, then click the button matching button_text

• method: "view_product" — show the product page URL to the user

Capabilities

• Product Search — semantic vs keyword vs GTIN, when to use which, filters, scoring

• Cart Actions — three action types, how to handle each

• Data Coverage — countries, data freshness, live stats

API Reference

Full documentation: api/reference.md

OpenAPI spec: api/openapi.yaml

Endpoints

Code Examples

• Semantic search — curl, Python, JavaScript

• Keyword search — curl, Python, JavaScript

• GTIN/EAN lookup — curl, Python, JavaScript

• Cart actions — handling all three action types

Rate Limits

300 requests per hour per IP address. Shared across REST API and MCP. No authentication needed.

429 responses include a Retry-After header.

Contributing

Found an issue with the docs? Open a PR:

1. Fork this repo

2. Edit the relevant file

3. Submit a pull request

Please keep changes consistent with api/reference.md as the source of truth for API behavior.

License

MIT