Etsy MCP Server

Give your AI assistant live access to Etsy. This Actor runs as a Model Context Protocol (MCP) server so agents such as Claude, ChatGPT, Cursor and n8n can search Etsy listings and shops, browse the category tree and fetch search suggestions on demand. It can also run once as a classic scraper that writes listing rows to a dataset.

It talks to Etsy's mobile app API, so no Etsy account, API key or browser is needed.

Who it is for

• AI and agent developers who want an Etsy "skill" for a shopping or research assistant.
• Etsy sellers and analysts asking questions such as "which candle shops have the most sales?" or "find the cheapest personalised leather wallets".
• Automation builders wiring Etsy lookups into n8n or Make agent flows.

MCP tools

Tool	What it does	Key arguments
search_etsy_listings	Search product listings by keyword with filters and sorting. Up to 200 per call.	keywords, limit, min_price, max_price, ship_to, sort_on, free_shipping, is_discounted, digital_only
search_etsy_shops	Find shops by name or keyword: owner, location, sales count, listing count, open date, sample listings.	query, limit, max_shop_listings
get_etsy_category	Walk Etsy's category tree one level at a time: top level ("0"), then sub-categories with listing counts.	taxonomy_id
get_etsy_search_suggestions	Autocomplete terms buyers type for a seed term, plus matching shops.	query, limit

Good to know:

• sort_on accepts score (relevance), best_seller, price_asc, price_desc, created_desc. best_seller uses Etsy's relevance order; the bestseller badge itself is returned per listing as is_bestseller.
• Etsy answers about 36 listings per search call and ignores paging, so larger limits run several price-band searches and results are deduplicated by listing id (200 listings take roughly 10-15 seconds). A narrow search can return fewer listings than requested.
• is_discounted filters to listings Etsy marks as on sale; the search response usually carries no discount amount.
• Listing rows come from Etsy's search response. They do not include tags, materials, descriptions or per-listing review ratings. shop_review_count and shop_sales_count describe the whole shop, not the single listing.
• A call that fails or returns nothing comes back as an error or an empty list and is not billed as a tool call.

Connect it

1. Open the Actor and enable Standby mode (it then exposes an HTTPS endpoint).
2. Point your MCP client at https://<your-username>--etsy-mcp-scraper.apify.actor/mcp (Streamable HTTP) and send your Apify API token as a Bearer token.
3. Ask your agent to use the Etsy tools.

{
    "mcpServers": {
        "etsy": {
            "type": "http",
            "url": "https://<your-username>--etsy-mcp-scraper.apify.actor/mcp",
            "headers": { "Authorization": "Bearer <APIFY_TOKEN>" }
        }
    }
}

Output fields (listings)

Field	Description
listing_id, title, url	Listing id, title and direct URL
shop_name, shop_url	Seller shop name and URL
price, original_price, discount_percent	Current price; pre-discount price and discount % only when Etsy's response includes them (often absent)
currency_code	Currency of the price
images, thumbnail	Image URLs and a thumbnail
shipping	Shipping destinations and costs
is_digital, is_vintage, is_handmade	Listing type flags
has_variations, personalization_available	Variations and personalisation flags
quantity, is_sold_out	Stock
is_bestseller, is_star_seller	Etsy performance badges
shop_review_count, shop_sales_count	The shop's total review count and sales count
scraped_at	UTC timestamp

Example tool call (trimmed)

search_etsy_listings with {"keywords": "ceramic coffee mug", "limit": 1, "sort_on": "best_seller"}:

{
    "query": "ceramic coffee mug",
    "count": 1,
    "results": [
        {
            "listing_id": "4296141840",
            "title": "Coffee Mug - KJ Pottery",
            "url": "https://www.etsy.com/listing/4296141840/coffee-mug-kj-pottery",
            "shop_name": "KJPottery",
            "price": 57.0,
            "currency_code": "USD",
            "is_digital": false,
            "is_bestseller": true,
            "is_star_seller": true,
            "shop_review_count": 3476
        }
    ]
}

One-shot (dataset) mode

Start the Actor normally (not Standby) with keywords to run a single search and write one row per listing to the dataset, ready for CSV, JSON or Excel export. It can be scheduled like any Actor.

Input	Meaning
keywords	Search terms (required)
limit	Max listings, 1-5000
minPrice / maxPrice	Price range filter
shipTo	ISO country code (US, GB, CA, ...)
sortOn	Relevance, best sellers, price, newest
freeShipping	Free-shipping listings only
isDiscounted	Discounted listings only
digitalOnly	Instant digital downloads only

{
    "keywords": "ceramic coffee mug",
    "limit": 10,
    "minPrice": 15,
    "maxPrice": 60,
    "sortOn": "price_asc",
    "freeShipping": true
}

Scheduling and automation

• Schedule one-shot runs from the Apify Console, for example daily price checks.
• Use webhooks to send results to your endpoint when a run finishes.
• Trigger runs through the Apify API: POST https://api.apify.com/v2/acts/<your-username>~etsy-mcp-scraper/runs.

FAQ

Do I need an Etsy API key? No. The Actor uses the same mobile endpoints the Etsy app calls.

Which MCP clients work? Any client that speaks Streamable HTTP MCP: Claude Desktop, ChatGPT custom connectors, Cursor, VS Code, n8n and custom agents.

Can I use it without MCP? Yes. Run it normally with keywords and read the dataset.

Why are tags and descriptions missing? Etsy's search response does not contain them; this Actor returns search-level data only.

What if Etsy changes something? Etsy has no public API for this data, so the Actor depends on the app endpoints. If a tool starts returning errors, open an issue on the Actor page.