Provides full access to the Etsy Open API v3 for both buyer browsing and seller shop management, including tools for managing listings, orders, shipping, inventory, and payments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Etsy MCP Server show me my recent shop orders"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides full access to the Etsy Open API v3. Supports both buyer browsing and seller shop management with 37 tools covering listings, orders, shipping, reviews, inventory, payments, and more.
Full Etsy API v3 coverage — 37 MCP tools wrapping ~70 API endpoints
OAuth 2.0 + PKCE — Secure browser-based authentication with automatic token refresh
Both buyer and seller workflows — Search listings, manage shops, process orders, handle shipping
Rate limiting — Concurrency-safe 10 req/sec limiter to respect Etsy's limits
Auto-retry — Exponential backoff on 429/5xx errors, automatic token refresh on 401
TypeScript — Full type safety with types generated from Etsy's official OpenAPI spec
Category | Tools |
Listings |
|
Shop |
|
Orders |
|
Transactions |
|
Shipping |
|
Reviews |
|
Users |
|
Taxonomy |
|
Images/Video |
|
Inventory |
|
Payments |
|
Return Policies |
|
Auth |
|
Related MCP server: Etsy MCP Server
git clone https://github.com/aserper/etsy-mcp.git
cd etsy-mcp
npm install
npm run builddocker pull ghcr.io/aserper/etsy-mcp:latestRegister at Etsy Developers to get your API credentials.
Variable | Required | Description |
| Yes | Your Etsy API keystring |
| Yes | Your Etsy shared secret |
Copy .env.example to .env and fill in your credentials:
cp .env.example .env{
"mcpServers": {
"etsy": {
"command": "node",
"args": ["/path/to/etsy-mcp/dist/index.js"],
"env": {
"ETSY_API_KEY": "your_keystring",
"ETSY_SHARED_SECRET": "your_shared_secret"
}
}
}
}docker run --rm \
-e ETSY_API_KEY=your_keystring \
-e ETSY_SHARED_SECRET=your_shared_secret \
ghcr.io/aserper/etsy-mcp:latestOn first use, call the authenticate tool. This opens your browser to Etsy's OAuth consent page using PKCE. After granting access, tokens are stored at ~/.etsy-mcp/tokens.json (owner-only permissions) and auto-refreshed when they expire.
npm install # Install dependencies
npm run build # Compile TypeScript
npm test # Run tests
npm run dev # Watch mode
npm run lint # Type check
npm run generate-types # Regenerate types from Etsy OAS specThis server covers the full Etsy Open API v3 (~70 endpoints). Features not available via the public API (messaging, cart, favorites, checkout) are out of scope.
MIT
Contributions welcome! Feel free to open an issue or submit a PR.
This project is not affiliated with, endorsed by, or associated with Etsy, Inc. It uses Etsy's publicly available Open API v3. Use responsibly and in accordance with Etsy's API Terms of Use.
Authenticate with Etsy via OAuth 2.0. Opens a browser for consent. Required before using tools that need user authorization.
Inputs: no named parameters.
Create a new draft listing in a shop
Inputs: shop_id (required), title (required), description (required), price (required), +11 more.
Create a shipment with tracking for a receipt
Inputs: shop_id (required), receipt_id (required), tracking_code, carrier_name, +1 more.
Create a new shipping profile for a shop
Inputs: shop_id (required), title (required), origin_country_iso (required), primary_cost (required), +4 more.
Delete a listing
Inputs: listing_id (required).
Delete an image from a listing
Inputs: shop_id (required), listing_id (required), listing_image_id (required).
Search for Etsy shops by name
Inputs: shop_name (required), limit, offset.
Get the full buyer taxonomy tree (categories)
Inputs: no named parameters.
Get payment account ledger entries for a shop
Inputs: shop_id (required), min_created, max_created, limit, +1 more.
Get details of a specific Etsy listing
Inputs: listing_id (required), includes.
Get all images for a listing
Inputs: listing_id (required).
Get inventory (products, offerings, variations) for a listing
Inputs: listing_id (required).
Get all listings for a shop, filterable by state
Inputs: shop_id (required), state, limit, offset.
Get the currently authenticated Etsy user
Inputs: no named parameters.
Get payments for a shop or a specific receipt (read-only)
Inputs: shop_id (required), receipt_id.
Get a specific receipt/order by ID
Inputs: shop_id (required), receipt_id (required).
Get all return policies for a shop
Inputs: shop_id (required).
Get reviews for a specific listing
Inputs: listing_id (required), limit, offset.
Get reviews for a shop
Inputs: shop_id (required), limit, offset.
List available shipping carriers by origin country
Inputs: origin_country_iso (required).
List all shipping profiles for a shop
Inputs: shop_id (required).
Get details of an Etsy shop by ID
Inputs: shop_id (required).
List orders/receipts for a shop with optional filters
Inputs: shop_id (required), min_created, max_created, was_paid, +3 more.
Get all sections of a shop
Inputs: shop_id (required).
Get properties for a specific taxonomy/category node
Inputs: taxonomy_id (required).
Get a specific transaction by ID
Inputs: shop_id (required), transaction_id (required).
Get all transactions for a specific receipt
Inputs: shop_id (required), receipt_id (required).
Get all transactions for a shop
Inputs: shop_id (required), limit, offset.
Get an Etsy user by ID
Inputs: user_id (required).
Get shipping addresses for a user
Inputs: user_id (required).
Create, update, or delete a return policy for a shop
Inputs: shop_id (required), action (required), return_policy_id, accepts_returns, +2 more.
Create or delete shipping destinations on a profile
Inputs: shop_id (required), shipping_profile_id (required), action (required), shipping_profile_destination_id, +4 more.
Create, update, or delete a shop section
Inputs: shop_id (required), action (required), shop_section_id, title.
Search active Etsy listings with keywords and filters
Inputs: keywords, taxonomy_id, min_price, max_price, +4 more.
Update an existing listing
Inputs: shop_id (required), listing_id (required), title, description, +6 more.
Update inventory for a listing (products with offerings and prices)
Inputs: listing_id (required), products (required).
Update a receipt (e.g., mark as shipped)
Inputs: shop_id (required), receipt_id (required), was_shipped, was_paid.
Update an existing shipping profile
Inputs: shop_id (required), shipping_profile_id (required), title, origin_country_iso, +4 more.
Update shop settings (requires shop owner auth)
Inputs: shop_id (required), title, announcement, sale_message, +2 more.
Upload an image to a listing from a local file path
Inputs: shop_id (required), listing_id (required), image_path (required), rank, +3 more.
Upload a video to a listing from a local file path (max 15 seconds)
Inputs: shop_id (required), listing_id (required), video_path (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 41 tools
Most tools have distinct purposes targeting specific Etsy resources (e.g., listings, receipts, shipping profiles), with clear boundaries. However, some overlap exists, such as 'get_reviews_by_listing' and 'get_reviews_by_shop', which could cause minor confusion if an agent needs reviews but isn't sure which to use. Overall, descriptions help differentiate tools effectively.
Tool names follow a highly consistent verb_noun pattern throughout, such as 'get_listing', 'update_listing', 'delete_listing', and 'search_listings'. All tools use snake_case with clear verbs (e.g., get, create, update, delete, manage), making them predictable and easy to understand. No deviations or mixed conventions are present.
With 41 tools, the count is borderline high for a single server, potentially overwhelming for agents. While Etsy's API is extensive, this many tools might feel heavy and could lead to complexity in tool selection. A more streamlined set might improve usability without sacrificing functionality.
The tool set provides comprehensive coverage of Etsy's domain, including full CRUD operations for key resources like listings, receipts, and shipping profiles. It covers authentication, search, management of images/videos, inventory, reviews, taxes, and shop settings, with no obvious gaps. Agents can handle complete workflows from listing creation to order fulfillment.
Etsy research and shop tools for AI: products, shops, keywords, trends, your listings and orders.
Research Etsy and manage an authorized shop; MakeBox Pro or Studio required.
Live Etsy data, read-only: listing and shop checks, shop sales count, top shops, tags and fees.
Etsy MCP — public listing search via Etsy Open API v3 (api_key auth only)