Heartly Developers

Heartly MCP Server

Live, time-bounded flash-sale inventory from verified Shopify and WooCommerce merchants worldwide, exposed via the Model Context Protocol. Public. Free. No auth required.

Endpoint

https://mcp.heartly.io/

Also reachable at https://www.heartly.io/mcp while DNS for the subdomain is being provisioned. Transport: Streamable HTTP. Stateless (no session token required).

Connect from Claude Desktop

Add this to your claude_desktop_config.json:

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

Restart Claude Desktop, then ask: “What flash sales are ending in Germany in the next 2 hours?”

Tools

Three tools, all read-only:

`list_active_deals`

List currently active flash-sale deals from verified Heartly merchants. Returns deals sorted by ending soonest. All filters optional.

Argument	Type	Description
country	string	ISO 3166-1 alpha-2 country code. Filters to merchants shipping to that country.
category	string	Top-level product category, e.g. "fashion", "beauty", "electronics".
min_discount_pct	integer 0-100	Only return deals at or above this discount percent.
ending_within_hours	integer 1-720	Only return deals ending within this many hours.

`search_deals_by_category`

Search active deals filtered by category. Category is required. Other filters (country, min_discount_pct, ending_within_hours) are optional.

Argument	Type	Description
category	string (required)	Top-level product category.
country	string	ISO 3166-1 alpha-2.
min_discount_pct	integer 0-100	Minimum discount percent.
ending_within_hours	integer 1-720	Only deals ending within this window.

`get_deal_by_id`

Look up a single active deal by its Heartly internal id (UUID).

Argument	Type	Description
id	string (UUID, required)	Heartly internal deal id.

Deal schema

Every tool returns deals shaped as:

{
  "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 (always true in v1 responses)"
}

Example queries

Five questions an AI agent can answer with this server:

What flash sales are ending in the next 2 hours in Germany?

Tool call

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

Show me fashion deals with at least 30% off in Austria.

Tool call

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

List all active beauty deals in DACH right now.

Tool call

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

What is the best discount available right now?

Tool call

list_active_deals({"min_discount_pct":50})

Look up deal id 7f3c8a12-... for details.

Tool call

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

Verified merchants only

The server returns deals only from merchants that are: active, not suspended, not a development store, not password-protected, not feed-frozen, and connected with valid Shopify or WooCommerce credentials. This is the same hygiene gate that powers deals.heartly.io.

Limitations (v1)

merchant_country reports a single representative code or ALL for worldwide shippers; merchants who ship to multiple specific countries surface their first listed country.
Read-only. No checkout, cart, or order operations. Purchase happens on the merchant store at product_url.
No authentication. Rate-limited at the Vercel edge.
Active deals only. Ended deals are not returned (use the public web at deals.heartly.io for tombstones).

Contact

Questions or integration help: ai@heartly.io.