@Mcpengine/Etsy

The most complete Model Context Protocol (MCP) server for the Etsy API v3, featuring 50+ tool modules covering virtually the entire Etsy API surface.

---

Features

• 50+ tools across every Etsy API domain
• Full Etsy API v3 coverage
• Zod-validated input schemas on every tool
• readOnlyHint on all GET/list operations
• destructiveHint on all delete operations
• Cursor/offset pagination on all list tools
• Axios-based client with OAuth bearer token support
• TypeScript with 0 compilation errors

---

Tools Index

Listings (Core)

Tool	Description
etsy_listings_list	List active listings with filters
etsy_listing_get	Get a single listing
etsy_listings_get_by_ids	Batch-fetch listings by IDs
etsy_listings_list_by_shop	List all listings in a shop
etsy_listing_create	Create a new listing
etsy_listing_update	Update a listing
etsy_listing_delete	Delete a listing
etsy_listings_featured	Get featured listings

Listing Images

Tool	Description
etsy_listing_images_list	List images for a listing
etsy_listing_image_get	Get a specific image
etsy_listing_image_upload	Upload an image via URL
etsy_listing_image_delete	Delete an image
etsy_listing_images_reorder	Reorder listing images

Listing Videos

Tool	Description
etsy_listing_videos_list	List videos
etsy_listing_video_get	Get a specific video
etsy_listing_video_upload	Upload/attach a video
etsy_listing_video_delete	Remove a video

Listing Inventory

Tool	Description
etsy_listing_inventory_get	Get inventory (variations, prices, quantities)
etsy_listing_inventory_update	Update inventory

Listing Properties

Tool	Description
etsy_listing_properties_list	List properties
etsy_listing_property_get	Get a property
etsy_listing_property_update	Update a property
etsy_listing_property_delete	Delete a property

Digital Files

Tool	Description
etsy_listing_files_list	List digital download files
etsy_listing_file_get	Get a file
etsy_listing_file_upload	Upload a digital file
etsy_listing_file_delete	Delete a file

Translations

Tool	Description
etsy_listing_translations_list	List translations
etsy_listing_translation_get	Get a translation
etsy_listing_translation_create	Create translation
etsy_listing_translation_update	Update translation

Variation Images

Tool	Description
etsy_listing_variation_images_get	Get variation images
etsy_listing_variation_images_update	Update variation images

Shops

Tool	Description
etsy_shop_get	Get a shop
etsy_shop_update	Update a shop
etsy_shops_by_owner	Get shops by user
etsy_shop_find	Search shops by name

Shop Sections

Tool	Description
etsy_shop_sections_list	List sections
etsy_shop_section_get	Get a section
etsy_shop_section_create	Create a section
etsy_shop_section_update	Update a section
etsy_shop_section_delete	Delete a section

Shop About, Production Partners, Return Policies

Tool	Description
etsy_shop_about_get	Get shop About page
etsy_shop_production_partners_list	List production partners
etsy_shop_production_partner_create	Create partner
etsy_shop_production_partner_update	Update partner
etsy_shop_production_partner_delete	Delete partner
etsy_shop_return_policies_list	List return policies
etsy_shop_return_policy_get	Get a policy
etsy_shop_return_policy_create	Create policy
etsy_shop_return_policy_update	Update policy
etsy_shop_return_policy_delete	Delete policy

Shipping Profiles

Tool	Description
etsy_shop_shipping_profiles_list	List profiles
etsy_shop_shipping_profile_get	Get a profile
etsy_shop_shipping_profile_create	Create profile
etsy_shop_shipping_profile_update	Update profile
etsy_shop_shipping_profile_delete	Delete profile
etsy_shipping_profile_destinations_list	List destinations
etsy_shipping_profile_destination_create	Create destination
etsy_shipping_profile_destination_update	Update destination
etsy_shipping_profile_destination_delete	Delete destination
etsy_shipping_profile_upgrades_list	List upgrades
etsy_shipping_profile_upgrade_create	Create upgrade
etsy_shipping_profile_upgrade_update	Update upgrade
etsy_shipping_profile_upgrade_delete	Delete upgrade
etsy_shipping_carriers_list	List shipping carriers

Orders & Receipts

Tool	Description
etsy_receipts_list	List orders/receipts
etsy_receipt_get	Get a receipt
etsy_receipt_update	Update receipt (ship, note)
etsy_receipt_transactions_list	List transactions
etsy_receipt_transaction_get	Get a transaction
etsy_receipt_transactions_by_receipt	Transactions for a receipt
etsy_receipt_shipments_list	List shipments
etsy_receipt_shipment_create	Add tracking
etsy_shop_receipt_transactions_list	Receipt transactions in shop
etsy_shop_listing_transactions_list	Listing transactions

Payments & Finance

Tool	Description
etsy_payments_list	List payments
etsy_payment_get	Get a payment
etsy_payments_by_receipt	Payments for a receipt
etsy_payment_ledger_entries_list	List ledger entries
etsy_payment_ledger_entry_get	Get a ledger entry
etsy_payment_account_get	Get payment account
etsy_ledger_entries_list	List ledger entries (alt)
etsy_ledger_entry_get	Get ledger entry
etsy_ledger_entry_payment_get	Payment for ledger entry
etsy_payouts_list	List payouts
etsy_payout_get	Get a payout

Reviews

Tool	Description
etsy_shop_reviews_list	Shop reviews
etsy_listing_reviews_list	Listing reviews

Users & Addresses

Tool	Description
etsy_user_get	Get a user
etsy_user_me	Get authenticated user
etsy_user_addresses_list	List addresses
etsy_user_address_get	Get an address
etsy_user_address_delete	Delete an address

Taxonomy & Discovery

Tool	Description
etsy_taxonomy_seller_list	List seller taxonomy
etsy_taxonomy_node_get	Get a taxonomy node
etsy_taxonomy_properties_list	List taxonomy properties
etsy_taxonomy_properties_get	Get properties for node
etsy_buyer_taxonomy_list	List buyer taxonomy
etsy_buyer_taxonomy_node_get	Get buyer taxonomy node
etsy_listings_search	Global listing search
etsy_shop_listings_search	Search within a shop
etsy_shop_listings_by_section	Listings by section

Favorites

Tool	Description
etsy_user_favorite_listings_list	List favorited listings
etsy_user_favorite_listing_get	Check if listing is favorited
etsy_user_favorite_listing_add	Favorite a listing
etsy_user_favorite_listing_remove	Unfavorite a listing
etsy_user_favorite_shops_list	List favorited shops
etsy_user_favorite_shop_get	Check if shop is favorited
etsy_user_favorite_shop_add	Favorite a shop
etsy_user_favorite_shop_remove	Unfavorite a shop

Images, Media & Icons

Tool	Description
etsy_listing_image_upload_url	Upload image from URL
etsy_listing_image_set_rank	Set image display rank
etsy_listing_image_update_alt	Update image alt text
etsy_shop_icon_get	Get shop icon
etsy_shop_icon_delete	Delete shop icon
etsy_shop_banner_get	Get shop banner
etsy_shop_banner_delete	Delete shop banner

Listing Lifecycle & Content

Tool	Description
etsy_listing_drafts_list	List draft listings
etsy_listing_draft_create	Create a draft
etsy_listing_draft_publish	Publish a draft
etsy_listing_renew	Renew an expired listing
etsy_listings_expired_list	List expired listings
etsy_listings_inactive_list	List inactive listings
etsy_listing_stats_get	Get listing stats
etsy_listing_views_get	Get view count
etsy_listings_stats_bulk	Bulk listing stats
etsy_featured_listings_list	List featured listings
etsy_listing_set_featured_rank	Set featured rank
etsy_listing_feature	Feature a listing
etsy_listing_unfeature	Unfeature a listing
etsy_listing_tags_get	Get listing tags
etsy_listing_tags_update	Replace tags
etsy_listing_tags_add	Add tags
etsy_listing_materials_get	Get materials
etsy_listing_materials_update	Replace materials
etsy_listing_materials_add	Add materials
etsy_listing_occasion_get	Get occasion
etsy_listing_occasion_set	Set occasion
etsy_listing_styles_update	Update styles

Shop Analytics

Tool	Description
etsy_shop_stats_get	Shop-level stats
etsy_shop_receipt_summary	Order summary
etsy_shop_payment_summary	Payment account summary

Products & Offerings

Tool	Description
etsy_listing_offering_get	Get a product offering
etsy_listing_product_get	Get a product variant

---

Setup

1. Get an Etsy API Key

1. Visit Etsy Developer Portal
2. Click Create a New App
3. Note your API Key (Keystring)
4. For write operations, set up OAuth 2.0 and obtain an access token

2. Install

npm install
npm run build

3. Configure

cp .env.example .env
# Edit .env with your credentials

ETSY_API_KEY=your_etsy_api_key_here
ETSY_ACCESS_TOKEN=your_oauth_access_token_here  # Optional: for write operations

4. Run

npm start

Or with npx:

ETSY_API_KEY=<key> node dist/main.js

---

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "etsy": {
      "command": "node",
      "args": ["/path/to/etsy-mcp/dist/main.js"],
      "env": {
        "ETSY_API_KEY": "your_api_key_here",
        "ETSY_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "etsy": {
      "command": "node",
      "args": ["./dist/main.js"],
      "env": {
        "ETSY_API_KEY": "your_api_key_here"
      }
    }
  }
}

---

Authentication

The Etsy API uses two forms of authentication:

Operation	Auth Required
Public listing search	API Key only
Read shop data	API Key only
Write/update operations	OAuth 2.0 Access Token
Financial data	OAuth 2.0 Access Token

API Key: Pass as ETSY_API_KEY env var
OAuth Token: Pass as ETSY_ACCESS_TOKEN env var

For OAuth setup, see Etsy's OAuth 2.0 Guide.

---

Architecture

src/
├── main.ts          # Entry point, env validation
├── server.ts        # MCP server class, tool loader
├── client.ts        # Axios-based Etsy API v3 client
├── types.ts         # TypeScript interfaces
└── tools/           # One file per API domain (47 modules)
    ├── listings.ts
    ├── listing_images.ts
    ├── ...
    └── listing_occasion.ts

---

Development

npm run dev     # ts-node (no build step)
npm run build   # TypeScript compile → dist/
npm run lint    # ESLint

---

License

MIT — see LICENSE