@mcpengine/etsy — The Most Comprehensive Etsy MCP Server
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
readOnlyHinton all GET/list operationsdestructiveHinton 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
- Visit Etsy Developer Portal
- Click Create a New App
- Note your API Key (Keystring)
- For write operations, set up OAuth 2.0 and obtain an access token
2. Install
npm install
npm run build3. Configure
cp .env.example .env
# Edit .env with your credentialsETSY_API_KEY=your_etsy_api_key_here
ETSY_ACCESS_TOKEN=your_oauth_access_token_here # Optional: for write operations4. Run
npm startOr with npx: ``bash 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
