Heartly Entwickler

Heartly MCP-Server

Aktuelle, zeitlich begrenzte Flash-Sale-Daten von verifizierten Shopify- und WooCommerce-Händlern weltweit, bereitgestellt über das Model Context Protocol. Öffentlich. Kostenlos. Keine Authentifizierung erforderlich.

Endpunkt

https://mcp.heartly.io/

Auch erreichbar unter https://www.heartly.io/mcp. Transport: Streamable HTTP. Stateless (kein Session-Token nötig).

Anbindung an Claude Desktop

Füge folgendes zu deiner claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "heartly": {
      "url": "https://mcp.heartly.io/"
    }
  }
}

Claude Desktop neu starten, dann fragen: „Welche Flash Sales laufen in den nächsten 2 Stunden in Deutschland aus?“

Tools

Drei Tools, alle nur lesend:

`list_active_deals`

Listet aktuell aktive Flash-Sale-Deals von verifizierten Heartly-Händlern auf. Liefert Deals sortiert nach Ablauf-Zeitpunkt. Alle Filter optional.

Argument	Typ	Beschreibung
country	string	ISO 3166-1 Alpha-2 Ländercode. Filtert auf Händler, die in dieses Land versenden.
category	string	Top-Level Produktkategorie, z. B. "fashion", "beauty", "electronics".
min_discount_pct	integer 0-100	Nur Deals mit mindestens diesem Rabatt-Prozentsatz.
ending_within_hours	integer 1-720	Nur Deals, die innerhalb dieses Zeitfensters enden.

`search_deals_by_category`

Sucht aktive Deals gefiltert nach Kategorie. Die Kategorie ist Pflicht. Andere Filter (country, min_discount_pct, ending_within_hours) sind optional.

Argument	Typ	Beschreibung
category	string (Pflicht)	Top-Level Produktkategorie.
country	string	ISO 3166-1 Alpha-2.
min_discount_pct	integer 0-100	Mindest-Rabatt in Prozent.
ending_within_hours	integer 1-720	Nur Deals innerhalb dieses Zeitfensters.

`get_deal_by_id`

Sucht einen einzelnen aktiven Deal über die interne Heartly-ID (UUID).

Argument	Typ	Beschreibung
id	string (UUID, Pflicht)	Interne Heartly Deal-ID.

Deal-Schema

Jedes Tool liefert Deals in folgender Form zurück:

{
  "id": "string (UUID)",
  "merchant": "string",
  "merchant_url": "string (URL)",
  "merchant_country": "string (ISO 3166-1 alpha-2)",
  "sku": "string",
  "product_title": "string",
  "product_url": "string (URL)",
  "original_price": "number",
  "sale_price": "number",
  "currency": "string (ISO 4217)",
  "discount_pct": "integer 0-100",
  "valid_from": "string (ISO 8601 datetime)",
  "valid_until": "string (ISO 8601 datetime)",
  "stock_remaining": "integer | null",
  "stock_capped": "boolean",
  "category": "string | null",
  "campaign_type": "standard_flash_sale | carousel | autopilot",
  "merchant_verified": "boolean (immer true in v1 Antworten)"
}

Beispiel-Abfragen

Fünf Fragen, die ein KI-Agent mit diesem Server beantworten kann:

Welche Flash Sales laufen in den nächsten 2 Stunden in Deutschland aus?

Tool-Aufruf

list_active_deals({"country":"DE","ending_within_hours":2})

Zeig mir Mode-Deals mit mindestens 30% Rabatt in Österreich.

Tool-Aufruf

search_deals_by_category({"category":"fashion","country":"AT","min_discount_pct":30})

Liste alle aktiven Beauty-Deals weltweit.

Tool-Aufruf

search_deals_by_category({"category":"beauty"})

Was ist gerade der beste verfügbare Rabatt?

Tool-Aufruf

list_active_deals({"min_discount_pct":50})

Schau Deal-ID 7f3c8a12-... nach.

Tool-Aufruf

get_deal_by_id({"id":"7f3c8a12-1234-5678-9abc-def012345678"})

Nur verifizierte Händler

Der Server liefert nur Deals von Händlern, die aktiv sind, nicht suspendiert, kein Development-Store, nicht passwortgeschützt, nicht feed-frozen, und mit gültigen Shopify- oder WooCommerce-Credentials verbunden. Dieselbe Hygiene-Schwelle wie bei deals.heartly.io.

Einschränkungen (v1)

merchant_country gibt einen einzigen repräsentativen Code zurück oder ALL für weltweite Versender; Händler, die in mehrere Länder versenden, zeigen ihr erstes gelistetes Land.
Nur lesend. Keine Checkout-, Warenkorb- oder Bestellvorgänge. Der Kauf erfolgt im Händler-Shop unter product_url.
Keine Authentifizierung. Rate-Limit am Vercel Edge.
Nur aktive Deals. Beendete Deals werden nicht zurückgegeben (siehe deals.heartly.io für Tombstones).

Kontakt

Fragen oder Integrationshilfe: ai@heartly.io.