@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
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

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 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: ``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

@mcpengine/etsy