Integrates with the Etsy Open API v3 to manage your own Etsy shop, including reading listings, orders, and shop settings; creating and editing draft listings; updating inventory; uploading listing images; publishing listings; and adding order tracking with preview-before-confirm write operations.
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-clean-mcp draft a new listing for a ceramic mug and show me the preview"
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 small MCP server for looking after your own Etsy shop through the Etsy Open API v3. It reads listings, orders and shop settings, and can create draft listings, edit them, upload images, publish and add tracking. Every change is previewed first and only sent when you confirm it.
Node 22+, TypeScript, stdio transport
Endpoints and field names checked against Etsy's OpenAPI spec (spec/etsy-openapi-v3.json)
Narrow OAuth scopes: shops_r listings_r listings_w transactions_r transactions_w
Sign in to Etsy with your shop account and open https://www.etsy.com/developers/register.
Create a personal app. Etsy may not accept the word "Etsy" in the app name, so pick
something else (for example phobic-shop-tool).
Wait for the app to be approved if Etsy asks for review. Personal-access apps only work for your own shop, which is all this server needs.
On https://www.etsy.com/developers/your-apps, open the app and note the keystring and the shared secret.
In the app settings, add this callback URL exactly (no trailing slash, lowercase):
http://localhost:3003/callbackIf you use a different port or path, put the same value in redirect_uri (see below).
Etsy compares the two character for character.
cd /home/karstein/src/etsy-clean-mcp
npm ci && npm run buildEither environment variables:
export ETSY_KEYSTRING=your-keystring
export ETSY_SHARED_SECRET=your-shared-secretor a config file (recommended):
mkdir -p ~/.config/etsy-clean-mcp && chmod 700 ~/.config/etsy-clean-mcp
cp config.example.toml ~/.config/etsy-clean-mcp/config.toml
chmod 600 ~/.config/etsy-clean-mcp/config.toml
# then edit keystring / shared_secretSetting | Env variable | config.toml key | Default |
App keystring |
|
| none |
App shared secret |
|
| none |
Callback URL |
|
|
|
Image upload folder |
|
|
|
Config folder |
|
|
Environment variables win over the file.
node dist/index.js loginThis opens Etsy in the browser (or prints the URL), waits on the callback URL for Etsy to
send you back, checks the state value, swaps the code for tokens with PKCE and stops
listening. Tokens are saved to ~/.config/etsy-clean-mcp/tokens.json (file mode 0600,
folder 0700). The access token lasts about an hour and is refreshed automatically; the
refresh token lasts about 90 days. Run login again after that.
node dist/index.js status # who is logged in and when the tokens expire(npm link makes the etsy-clean-mcp command available instead of node dist/index.js.)
For example:
claude mcp add etsy -- node /home/karstein/src/etsy-clean-mcp/dist/index.jsRelated MCP server: Etsy MCP Server
Read:
Tool | What it does |
| Shop name, URL, currency, counts, reviews |
| Listings by state (active, inactive, sold_out, draft, removed, expired) |
| One listing with images and inventory (products, prices, quantities, SKUs) |
| Shipping profiles with destinations and costs |
| Return policies |
| Processing profiles ( |
| Shop sections |
| Find category ids; the category tree is cached for a day |
| Orders |
| One order with items, totals, address and shipments |
Write (all take confirm, default false):
Tool | What it does |
| New listing, always as a draft |
| Title, description, tags, materials, section, profiles, category |
| Price, quantity, SKU per product |
| Upload a jpg/png/gif/webp from the upload folder |
| Publish a draft or inactive listing (costs a listing fee) |
| Mark an order shipped; Etsy emails the buyer |
Prices come back as readable text, e.g. 1299.00 NOK.
Preview first. Every write tool returns the exact request it would send when
confirm is false and sends nothing. Only confirm: true sends.
(update_inventory reads the current inventory to build its preview, since Etsy
replaces the whole inventory on update.)
No deleting. There is no delete tool and the listings_d scope is never requested.
Drafts only. New listings are always created as drafts. Publishing is the separate
activate_listing tool, and its preview warns that Etsy charges a listing fee.
Upload folder only. Images are read only from inside the upload folder. Symlinks are resolved first; anything outside the folder, or not jpg/png/gif/webp, is refused.
Writes are never retried. Only GET requests are retried (on 429 and 5xx, honouring
Retry-After, with backoff). POST, PUT and PATCH are sent once.
Etsy's own error text is passed through with the HTTP status.
Secrets stay put. Tokens and the shared secret are never logged or returned by tools.
Advertising checklist. Titles over 40 characters or in ALL CAPS get a warning (not a block), following Etsy's own advice.
npm test # vitest, no network
npm run typecheck
npm run buildtest/spec.test.ts checks every endpoint the client can call (method, path and body type),
the enum values used by the tools, and the fields the write tools send, against
spec/etsy-openapi-v3.json. To refresh the spec, download
https://www.etsy.com/openapi/generated/oas/3.0.0.json over it and run the tests.
MIT, see LICENSE.
Publish a draft or inactive listing (state -> active). COSTS AN ETSY LISTING FEE. confirm=false previews.
Inputs: listing_id (required), confirm.
Add tracking to an order and mark it shipped. Etsy emails the buyer. confirm=false previews.
Inputs: receipt_id (required), carrier_name (required), tracking_code (required), confirm, +1 more.
Create a new listing as a DRAFT (never published). confirm=false previews. Physical listings also need shipping_profile_id and readiness_state_id before they can be activated.
Inputs: price (required), title (required), quantity (required), who_made (required), +13 more.
One listing with details, images and inventory (products, prices, quantities, SKUs).
Inputs: listing_id (required).
Your Etsy shop: name, URL, currency, counts, reviews.
Inputs: no named parameters.
One order: items, totals, buyer message, shipping address, shipments.
Inputs: receipt_id (required).
List your shop's listings by state (default active).
Inputs: limit, state, offset.
Your processing profiles (readiness_state_id + processing days), needed for physical listings.
Inputs: no named parameters.
Your orders (receipts), newest first. Filter by paid/shipped.
Inputs: limit, offset, was_paid, was_shipped.
Your return policies.
Inputs: no named parameters.
Your shipping profiles with destinations and costs.
Inputs: no named parameters.
Your shop sections.
Inputs: no named parameters.
Find seller taxonomy ids (categories) by words, e.g. 'wall clock'. Prefer leaf entries.
Inputs: query (required).
Set price, quantity and/or SKU per product. Omit product_id when the listing has a single product. confirm=false reads the current inventory and previews the full update.
Inputs: changes (required), listing_id (required), confirm.
Change listing text and settings (title, description, tags, materials, section, profiles, category). Not price/quantity: use update_inventory. confirm=false previews.
Inputs: listing_id (required), tags, title, confirm, +10 more.
Upload a jpg/png/gif/webp image to a listing. The file must be inside the upload folder (/root/Etsy/upload); relative paths are taken from there. confirm=false checks the file and previews.
Inputs: path (required), listing_id (required), rank, confirm, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 16 tools
Each tool has a clear resource+action identity: read tools target distinct shop resources (shop, policies, profiles, sections, taxonomy, receipts, listings), and write tools split cleanly along listing lifecycle (create_draft_listing, update_listing, update_inventory, upload_listing_image, activate_listing) plus order fulfillment (add_tracking). The descriptions explicitly resolve the one plausible overlap by stating that price/quantity belong to update_inventory, not update_listing.
All 16 names follow a strict snake_case verb_noun pattern (get_*, list_*, create_*, update_*, upload_*, activate_*, add_*), with singular/plural nouns used correctly for single-resource vs collection operations. No camelCase or verb-style drift.
16 tools is at the upper edge for a shop-management server, but most earn their place given the breadth of the domain (listings, inventory, images, orders, taxonomy, shop config). A few read-only reference lookups (policies, sections, processing profiles, shipping profiles) could arguably be consolidated, but none are redundant with each other.
Listing creation/update/inventory/image/publish and order read+tracking are covered, but the lifecycle has a dead end: activate_listing exists with no deactivate or delete_listing counterpart, and images cannot be deleted or reordered. Reference data is read-only (policies, shipping/processing profiles, sections can only be listed, not created), which will block agents from fully setting up a shop.
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)
Etsy research and shop tools for AI: products, shops, keywords, trends, your listings and orders.