Etsy MCP Server

A Model Context Protocol (MCP) server that provides integration with the Etsy API v3. This server enables AI assistants to search for products, get shop information, retrieve listing details, and more on Etsy.

Features

• 🔍 Search Listings: Search for active products on Etsy with filters

• 🏪 Shop Information: Get detailed shop data and reviews

• 📦 Listing Details: Retrieve comprehensive product information with images

• 🔥 Trending Products: Discover what's currently popular on Etsy

• ⭐ Reviews: Access shop reviews and ratings

• 📊 Pagination Support: Handle large result sets efficiently

Prerequisites

• Node.js 18 or higher

• An Etsy API key (from Etsy Developer Portal)

Getting an Etsy API Key

1. Go to Etsy Developers

2. Sign in with your Etsy account

3. Create a new app in the Developer Console

4. Copy your API Key (also called "Keystring")

Note: For read-only operations (searching, viewing public data), you only need an API key. For operations that modify data (creating listings, managing shops), you would need OAuth 2.0 authentication, which is not currently implemented in this server.

Installation

From npm (when published)

From Source

Configuration

Claude Desktop Configuration

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

Or if installed from source:

Environment Variable

Alternatively, you can set the API key as an environment variable:

Available Tools

search_listings

Search for active listings on Etsy.

Parameters:

• keywords (required): Search terms

• limit (optional): Number of results (1-100, default: 25)

• offset (optional): Pagination offset (default: 0)

• min_price (optional): Minimum price filter

• max_price (optional): Maximum price filter

• sort_on (optional): Sort by created, price, updated, or score

• sort_order (optional): asc, desc, ascending, or descending

Example:

get_listing_details

Get detailed information about a specific listing.

Parameters:

• listing_id (required): Numeric listing ID

• includes (optional): Array of additional data (Shop, Images, User, Videos, Inventory)

Example:

get_shop_by_name

Retrieve information about a shop by its name.

Parameters:

• shop_name (required): Shop name/slug

Example:

get_shop_listings

Get all active listings from a specific shop.

Parameters:

• shop_id (required): Numeric shop ID

• limit (optional): Number of results (1-100, default: 25)

• offset (optional): Pagination offset

• sort_on (optional): Sort field

• sort_order (optional): Sort direction

Example:

search_shops

Search for shops by name.

Parameters:

• shop_name (required): Shop name to search

• limit (optional): Number of results (1-100, default: 25)

• offset (optional): Pagination offset

Example:

get_trending_listings

Get currently trending listings on Etsy.

Parameters:

• limit (optional): Number of results (1-100, default: 25)

• offset (optional): Pagination offset

Example:

get_shop_reviews

Get reviews for a specific shop.

Parameters:

• shop_id (required): Numeric shop ID

• limit (optional): Number of results (1-100, default: 25)

• offset (optional): Pagination offset

• min_created (optional): Unix timestamp for minimum date

• max_created (optional): Unix timestamp for maximum date

Example:

Development

Build

Watch Mode

Development Mode

API Rate Limits

Etsy's API has rate limits:

• 10 requests per second per API key

• Be mindful of pagination when retrieving large datasets

Error Handling

The server includes comprehensive error handling:

• Invalid API keys return authentication errors

• Missing required parameters return validation errors

• Rate limit errors are surfaced to the user

• Network errors are caught and reported

Limitations

• Read-only: This server only supports read operations (searching, viewing)

• Public data only: Can only access publicly available information

• OAuth not implemented: Cannot perform authenticated operations like managing listings or accessing private shop data

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

MIT

Resources

• Etsy API Documentation

• Model Context Protocol

• MCP TypeScript SDK

Troubleshooting

"ETSY_API_KEY environment variable is required"

Make sure you've set the ETSY_API_KEY in your configuration file or environment variables.

"Authentication failed"

Verify your API key is correct and active in the Etsy Developer Portal.

"Rate limit exceeded"

Wait a moment before making more requests. Consider implementing delays between requests if making many calls.

Connection Issues

Ensure you have internet connectivity and that Etsy's API is accessible from your network.