Guide MCP Server

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

For the complete tool reference (input schemas, sample responses, tier-by-tier field differences), see 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.

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.

Claude Code

Run the following command in your terminal:

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

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

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

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"
    }
  }
}

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: mcp@idealo.de
• Request support for a new MCP client: mcp@idealo.de