Etsy Server

Tests License Node Docker

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	search_listings, get_listing, create_draft_listing, update_listing, delete_listing, get_listings_by_shop
Shop	get_shop, update_shop, find_shops, get_shop_sections, manage_shop_sections
Orders	get_shop_receipts, get_receipt, update_receipt, create_shipment
Transactions	get_transactions_by_shop, get_transaction, get_transactions_by_receipt
Shipping	get_shipping_profiles, create_shipping_profile, update_shipping_profile, manage_shipping_destinations, get_shipping_carriers
Reviews	get_reviews_by_listing, get_reviews_by_shop
Users	get_me, get_user, get_user_addresses
Taxonomy	get_buyer_taxonomy, get_taxonomy_properties
Images/Video	get_listing_images, upload_listing_image, upload_listing_video, delete_listing_image
Inventory	get_listing_inventory, update_listing_inventory
Payments	get_payments, get_ledger_entries
Return Policies	get_return_policies, manage_return_policy
Auth	authenticate

Installation

From source

git clone https://github.com/aserper/etsy-mcp.git
cd etsy-mcp
npm install
npm run build

Docker

docker pull ghcr.io/aserper/etsy-mcp:latest

Configuration

Register at Etsy Developers to get your API credentials.

Variable	Required	Description
ETSY_API_KEY	Yes	Your Etsy API keystring
ETSY_SHARED_SECRET	Yes	Your Etsy shared secret

Copy .env.example to .env and fill in your credentials:

cp .env.example .env

Usage

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

Authentication

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 spec

API 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.