{
  "markdown": "# idealo MCP Server Guide\n\nThe idealo MCP server brings idealo's product intelligence directly into your AI assistant — search products, compare prices across hundreds of shops, and analyse 30-day price history across 6 European marketplaces (DE, AT, GB, FR, IT, ES) without ever leaving your editor.\n\n> [!NOTE]\n> Rate limits apply to all idealo MCP server tools.\n> <br><br>\n> The default **Trial** tier is self-serve via OAuth and gives you `3 req/s · 6 burst · 500 calls/day` per user. Trial responses include a single product image, cap `get_product_offers` at 10 offers per product, and exclude shop logos, external links, and detailed user reviews.\n> <br><br>\n> **Partner tier** unlocks higher rate limits, full image arrays, shop logos, test-report links, and full user-review payloads. To request Partner access, contact us via mcp@idealo.de.\n\nFor the complete tool reference (input schemas, sample responses, tier-by-tier field differences), see **[docs/tools.md](./docs/tools.md)**.\n\n## Features\n\n- **Catalog search** — Full-text search with filters for category, brand, price range, availability, and bargains across 6 European marketplaces. Returns an encrypted `productRef` you pass to the other tools.\n\n- **Product details** — Fetch a complete product profile: top offers, reviews summary, expert review, test reports, technical specifications, pros/cons, and a 30-day price trend in a single call.\n\n- **Paginated offers** — Walk every offer for a product with shop name, ratings, pricing breakdown, delivery estimates, payment methods, free-return policy, and shipping costs. 5 offers per page.\n\n- **Price history & analytics** — 30-day price trend with min/max/avg statistics, percentage change, sampling granularity, ASCII chart, and AI-generated buying recommendations.\n\n## Installation & Setup\n\nDifferent MCP clients require slightly different setups. Follow the instructions below for your specific client.\n\n### Claude Desktop\n\nThe recommended way is via **Custom Connectors**:\n\n1. Open Claude → **Settings → Connectors**.\n2. Click **Add custom connector**.\n3. Enter the URL `https://mcp.idealo.com/mcp` and click **Add**.\n4. Authenticate when prompted — Claude opens a browser for the OAuth handshake.\n\n<details>\n<summary>Manual setup</summary>\n\nAdd the following to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or the equivalent on your platform:\n\n```json\n{\n  \"mcpServers\": {\n    \"idealo\": {\n      \"type\": \"url\",\n      \"url\": \"https://mcp.idealo.com/mcp\"\n    }\n  }\n}\n```\n\nRestart Claude Desktop and confirm the `idealo` server is listed under MCP tools.\n\n</details>\n\n### Claude Code\n\nRun the following command in your terminal:\n\n```bash\nclaude mcp add --transport http idealo https://mcp.idealo.com/mcp --callback-port 6274\n```\n\n<details>\n<summary>Manual setup</summary>\n\nAdd to `.mcp.json` at the project root (Claude Code reads it automatically):\n\n```json\n{\n  \"mcpServers\": {\n    \"idealo\": {\n      \"type\": \"url\",\n      \"url\": \"https://mcp.idealo.com/mcp\",\n      \"oauth\": {\n        \"callbackPort\": 6274\n      }\n    }\n  }\n}\n```\n\nUseful commands:\n\n- `claude mcp list` — list configured servers\n- `claude mcp get idealo` — show server details\n- `claude mcp remove idealo` — remove the server\n\n</details>\n\n### VS Code\n\n1. Use the shortcut `⌘ Shift P` to search for `MCP: Add Server`.\n2. Select `HTTP`.\n3. Paste `https://mcp.idealo.com/mcp` and hit `Enter`.\n4. When prompted for a server ID, enter `idealo`.\n5. Choose **global** or **workspace** scope.\n\nThe resulting `mcp.json` will look like:\n\n```json\n{\n  \"servers\": {\n    \"idealo\": {\n      \"type\": \"http\",\n      \"url\": \"https://mcp.idealo.com/mcp\"\n    }\n  }\n}\n```\n\nOpen the chat toolbar, switch to **Agent** mode, and type `#search_products` to confirm the tools are available. If nothing shows up, restart VS Code.\n\n> [!NOTE]\n> You must have [GitHub Copilot](https://github.com/features/copilot) enabled to use MCP in VS Code.\n\n### Cursor\n\n<details>\n<summary>Manual setup</summary>\n\n1. Open **Cursor → Settings → Cursor Settings**.\n2. Go to the **MCP** tab.\n3. Click **+ Add new global MCP server**.\n4. Enter and save:\n\n```json\n{\n  \"mcpServers\": {\n    \"idealo\": {\n      \"url\": \"https://mcp.idealo.com/mcp\"\n    }\n  }\n}\n```\n\n</details>\n\n### Other editors\n\nAny client that supports the **Streamable HTTP** transport can connect. Use:\n\n```json\n{\n  \"mcpServers\": {\n    \"idealo\": {\n      \"url\": \"https://mcp.idealo.com/mcp\"\n    }\n  }\n}\n```\n\n## Authentication\n\nThe server uses OAuth 2.0 with **Dynamic Client Registration (DCR) + PKCE**. Spec-compliant MCP clients discover the auth flow automatically through `.well-known/oauth-protected-resource` — no `client_id` / `client_secret` setup required for the Trial tier. On first connect, your client opens a browser for login. Tokens are cached client-side and refreshed transparently.\n\nPartner-tier credentials are issued separately by idealo upon request.\n\n## Prompting your MCP client\n\nOnce connected, prompt your client in plain language. The 4 tools chain together via an opaque `productRef` returned by `search_products`.\n\nExamples:\n\n- *\"Find running shoes under €100 available in Germany.\"*\n- *\"Show me details, top offers, and pros/cons for the cheapest result.\"*\n- *\"Walk through every offer until I see one that ships free with PayPal accepted.\"*\n- *\"Give me the 30-day price history and tell me whether now is a good time to buy.\"*\n\n## Tips & Best Practices\n\n- **Use `productRef`.** `search_products` returns an encrypted `productRef` per result — pass that string directly to `get_product_details`, `get_product_offers`, and `get_product_price_history`. It's opaque, marketplace-aware, and short-lived.\n- **`includeSearchFilters` and `includeSizeFilters` require `includeCategories`.** The server rejects calls that send attribute or size filters without at least one numeric category ID. Search first without filters to discover available `categoryId`s in the response.\n- **Pick the right country.** Pass `country` as a 2-letter ISO code (`DE`, `AT`, `GB`, `FR`, `IT`, `ES`). Unknown codes silently fall back to Germany.\n- **Paginate offers properly.** `get_product_offers` returns 5 offers per call plus a `nextOffset`. Loop until `nextOffset === 0`.\n- **Some shops are filtered out.** Compliance blocklist removes Amazon, eBay, and Otto offers from all tiers — this is intentional and applies regardless of tier.\n- **Hit the same marketplace consistently.** A `productRef` from `country=DE` won't return useful data when reused with `country=GB`.\n\n## Supported markets\n\n🇩🇪 Germany · 🇬🇧 United Kingdom · 🇫🇷 France · 🇮🇹 Italy · 🇪🇸 Spain · 🇦🇹 Austria\n\n## Support\n\n- Website: [idealo.de](https://www.idealo.de)\n- Tool reference: [docs/tools.md](./docs/tools.md)\n- Partner-tier requests: mcp@idealo.de\n- Request support for a new MCP client: mcp@idealo.de\n",
  "bytes": 6820,
  "sha": "ebcd37ec6e7a935ad72166cf1f878b56b4be04bfb8dd3c8f511731bb094e4358",
  "repo_slug": "idealo/mcp-server-guide",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_com_idealo_mcp_mcp_3438dc7d/readme"
}