idealo MCP Server Guide

The 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.

[!NOTE] Rate limits apply to all idealo MCP server tools. <br><br> 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. <br><br> 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 [email protected].

For the complete tool reference (input schemas, sample responses, tier-by-tier field differences), see [docs/tools.md](./docs/tools.md).

Features

• 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.

• 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.

• 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.

• Price history & analytics — 30-day price trend with min/max/avg statistics, percentage change, sampling granularity, ASCII chart, and AI-generated buying recommendations.

Installation & Setup

Different MCP clients require slightly different setups. Follow the instructions below for your specific client.

Claude Desktop

The recommended way is via Custom Connectors:

1. Open Claude → Settings → Connectors.
2. Click Add custom connector.
3. Enter the URL https://mcp.idealo.com/mcp and click Add.
4. Authenticate when prompted — Claude opens a browser for the OAuth handshake.

<details> <summary>Manual setup</summary>

Add the following to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "idealo": {
      "type": "url",
      "url": "https://mcp.idealo.com/mcp"
    }
  }
}

Restart Claude Desktop and confirm the idealo server is listed under MCP tools.

</details>

Claude Code

Run the following command in your terminal:

claude mcp add --transport http idealo https://mcp.idealo.com/mcp --callback-port 6274

<details> <summary>Manual setup</summary>

Add to .mcp.json at the project root (Claude Code reads it automatically):

{
  "mcpServers": {
    "idealo": {
      "type": "url",
      "url": "https://mcp.idealo.com/mcp",
      "oauth": {
        "callbackPort": 6274
      }
    }
  }
}

Useful commands:

• claude mcp list — list configured servers
• claude mcp get idealo — show server details
• claude mcp remove idealo — remove the server

</details>

VS Code

1. Use the shortcut ⌘ Shift P to search for MCP: Add Server.
2. Select HTTP.
3. Paste https://mcp.idealo.com/mcp and hit Enter.
4. When prompted for a server ID, enter idealo.
5. Choose global or workspace scope.

The resulting mcp.json will look like:

{
  "servers": {
    "idealo": {
      "type": "http",
      "url": "https://mcp.idealo.com/mcp"
    }
  }
}

Open the chat toolbar, switch to Agent mode, and type #search_products to confirm the tools are available. If nothing shows up, restart VS Code.

[!NOTE] You must have GitHub Copilot enabled to use MCP in VS Code.

Cursor

<details> <summary>Manual setup</summary>

1. Open Cursor → Settings → Cursor Settings.
2. Go to the MCP tab.
3. Click + Add new global MCP server.
4. Enter and save:

{
  "mcpServers": {
    "idealo": {
      "url": "https://mcp.idealo.com/mcp"
    }
  }
}

</details>

Other editors

Any client that supports the Streamable HTTP transport can connect. Use:

{
  "mcpServers": {
    "idealo": {
      "url": "https://mcp.idealo.com/mcp"
    }
  }
}

Authentication

The 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.

Partner-tier credentials are issued separately by idealo upon request.

Prompting your MCP client

Once connected, prompt your client in plain language. The 4 tools chain together via an opaque productRef returned by search_products.

Examples:

• "Find running shoes under €100 available in Germany."
• "Show me details, top offers, and pros/cons for the cheapest result."
• "Walk through every offer until I see one that ships free with PayPal accepted."
• "Give me the 30-day price history and tell me whether now is a good time to buy."

Tips & Best Practices

• 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.
• `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 categoryIds in the response.
• 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.
• Paginate offers properly. get_product_offers returns 5 offers per call plus a nextOffset. Loop until nextOffset === 0.
• Some shops are filtered out. Compliance blocklist removes Amazon, eBay, and Otto offers from all tiers — this is intentional and applies regardless of tier.
• Hit the same marketplace consistently. A productRef from country=DE won't return useful data when reused with country=GB.

Supported markets

🇩🇪 Germany · 🇬🇧 United Kingdom · 🇫🇷 France · 🇮🇹 Italy · 🇪🇸 Spain · 🇦🇹 Austria

Support

• Website: idealo.de
• Tool reference: docs/tools.md
• Partner-tier requests: [email protected]
• Request support for a new MCP client: [email protected]