Etsy MCP Server
Provides full access to the Etsy Open API v3, exposing 37 tools covering both buyer browsing and seller shop management: searching and retrieving listings, creating/updating/deleting draft listings, managing shops and shop sections, handling orders (receipts, transactions, shipments), shipping profiles and destinations, listing images and videos, inventory, payments and ledger entries, reviews, return policies, user addresses, and taxonomy. Authenticates via Etsy OAuth 2.0 with PKCE and automatically refreshes tokens.
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 search Etsy for handmade ceramic mugs under $30"
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.
Etsy MCP Server
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.
Features
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
Installation
From source
git clone https://github.com/aserper/etsy-mcp.git
cd etsy-mcp
npm install
npm run buildDocker
docker pull ghcr.io/aserper/etsy-mcp:latestConfiguration
Register 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 .envUsage
Claude Desktop Configuration
{
"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
docker run --rm \
-e ETSY_API_KEY=your_keystring \
-e ETSY_SHARED_SECRET=your_shared_secret \
ghcr.io/aserper/etsy-mcp:latestAuthentication
On 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.
Development
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 specAPI Coverage
This 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.
License
MIT
Contributing
Contributions welcome! Feel free to open an issue or submit a PR.
Disclaimer
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.
Available Tools
41 toolsauthenticateA
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_draft_listingC
Create a new draft listing in a shop
Inputs: price (required), title (required), shop_id (required), quantity (required), +11 more.
create_shipmentC
Create a shipment with tracking for a receipt
Inputs: shop_id (required), receipt_id (required), send_bcc, carrier_name, +1 more.
create_shipping_profileC
Create a new shipping profile for a shop
Inputs: title (required), shop_id (required), primary_cost (required), secondary_cost (required), +4 more.
delete_listingC
Delete a listing
Inputs: listing_id (required).
delete_listing_imageC
Delete an image from a listing
Inputs: shop_id (required), listing_id (required), listing_image_id (required).
find_shopsC
Search for Etsy shops by name
Inputs: shop_name (required), limit, offset.
get_buyer_taxonomyB
Get the full buyer taxonomy tree (categories)
Inputs: no named parameters.
get_ledger_entriesC
Get payment account ledger entries for a shop
Inputs: shop_id (required), limit, offset, max_created, +1 more.
get_listingB
Get details of a specific Etsy listing
Inputs: listing_id (required), includes.
get_listing_imagesC
Get all images for a listing
Inputs: listing_id (required).
get_listing_inventoryC
Get inventory (products, offerings, variations) for a listing
Inputs: listing_id (required).
get_listings_by_shopC
Get all listings for a shop, filterable by state
Inputs: shop_id (required), limit, state, offset.
get_meA
Get the currently authenticated Etsy user
Inputs: no named parameters.
get_paymentsC
Get payments for a shop or a specific receipt (read-only)
Inputs: shop_id (required), receipt_id.
get_receiptC
Get a specific receipt/order by ID
Inputs: shop_id (required), receipt_id (required).
get_return_policiesC
Get all return policies for a shop
Inputs: shop_id (required).
get_reviews_by_listingC
Get reviews for a specific listing
Inputs: listing_id (required), limit, offset.
get_reviews_by_shopC
Get reviews for a shop
Inputs: shop_id (required), limit, offset.
get_shipping_carriersC
List available shipping carriers by origin country
Inputs: origin_country_iso (required).
get_shipping_profilesB
List all shipping profiles for a shop
Inputs: shop_id (required).
get_shopB
Get details of an Etsy shop by ID
Inputs: shop_id (required).
get_shop_receiptsC
List orders/receipts for a shop with optional filters
Inputs: shop_id (required), limit, offset, was_paid, +3 more.
get_shop_sectionsC
Get all sections of a shop
Inputs: shop_id (required).
get_taxonomy_propertiesC
Get properties for a specific taxonomy/category node
Inputs: taxonomy_id (required).
get_transactionC
Get a specific transaction by ID
Inputs: shop_id (required), transaction_id (required).
get_transactions_by_receiptB
Get all transactions for a specific receipt
Inputs: shop_id (required), receipt_id (required).
get_transactions_by_shopC
Get all transactions for a shop
Inputs: shop_id (required), limit, offset.
get_userC
Get an Etsy user by ID
Inputs: user_id (required).
get_user_addressesC
Get shipping addresses for a user
Inputs: user_id (required).
manage_return_policyC
Create, update, or delete a return policy for a shop
Inputs: action (required), shop_id (required), accepts_returns, return_deadline, +2 more.
manage_shipping_destinationsC
Create or delete shipping destinations on a profile
Inputs: action (required), shop_id (required), shipping_profile_id (required), primary_cost, +4 more.
manage_shop_sectionsC
Create, update, or delete a shop section
Inputs: action (required), shop_id (required), title, shop_section_id.
search_listingsB
Search active Etsy listings with keywords and filters
Inputs: limit, offset, sort_on, keywords, +4 more.
update_listingC
Update an existing listing
Inputs: shop_id (required), listing_id (required), tags, price, +6 more.
update_listing_inventoryC
Update inventory for a listing (products with offerings and prices)
Inputs: products (required), listing_id (required).
update_receiptC
Update a receipt (e.g., mark as shipped)
Inputs: shop_id (required), receipt_id (required), was_paid, was_shipped.
update_shipping_profileC
Update an existing shipping profile
Inputs: shop_id (required), shipping_profile_id (required), title, primary_cost, +4 more.
update_shopB
Update shop settings (requires shop owner auth)
Inputs: shop_id (required), title, announcement, sale_message, +2 more.
upload_listing_imageC
Upload an image to a listing from a local file path
Inputs: shop_id (required), image_path (required), listing_id (required), rank, +3 more.
upload_listing_videoB
Upload a video to a listing from a local file path (max 15 seconds)
Inputs: shop_id (required), listing_id (required), video_path (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 41 tools
Most tools are clearly separated by resource and action (e.g., get_listing, create_draft_listing, delete_listing; reviews by listing vs. shop). A few boundaries are softer, especially bundled manage_* tools and the overlap between update_receipt and create_shipment, but descriptions mostly resolve them.
The set predominantly follows a verb_noun snake_case pattern with get_, create_, update_, delete_, upload_, and manage_. Minor deviations include find_shops vs. search_listings and bundled manage_* names, but the convention remains readable and predictable.
At 41 tools, the surface is heavy for an MCP server and includes several variants that could be consolidated. Bundled manage_* tools help slightly, but the count is still well above a well-scoped 3-15 tool range for most agent workflows.
Coverage is broad across listings, shops, sections, receipts, transactions, shipping, reviews, taxonomy, inventory, payments, and return policies. Minor gaps exist, such as no standalone delete for shipping profiles and limited lifecycle support around listing videos, but core seller workflows are covered.
Maintenance
Related MCP Connectors
Etsy research and shop tools for AI: products, shops, keywords, trends, your listings and orders.
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)
Etsy SEO, keyword research, listing creation and shop management for Etsy sellers.
Related MCP Servers
- FlicenseNot gradedqualityNot gradedmaintenanceEnables seamless integration with Etsy's marketplace API v3 to search listings, manage shop inventory, create and update products, optimize SEO, and access seller resources with OAuth support for authenticated operations.5-
- AlicenseAqualityDmaintenanceEnables AI assistants to search for products, retrieve listing details, get shop information, discover trending items, and access reviews on Etsy through the Etsy API v3.721MIT
- AlicenseBqualityDmaintenanceProvides full access to the Etsy Open API v3 for both buyer browsing and seller shop management through 37 specialized tools. It enables users to manage listings, process orders, handle shipping, and access inventory data via secure OAuth 2.0 authentication.4113MIT
- FlicenseBqualityCmaintenanceEnables Etsy sellers to manage their shops via natural language, including listing CRUD, bulk price and quantity updates by SKU, whole-shop A-F grade audits, photo uploads, shipping profiles, conversations, receipts, fulfillment tracking, and profit calculation.19-