A Model Context Protocol (MCP) server that provides seamless integration with the Etsy API v3. This server enables AI assistants and applications to interact with Etsy's marketplace, search listings, retrieve shop information, and access product details.

🚀 Deploy to Smithery: This server is ready for deployment to Smithery for hosted, always-available access. See SMITHERY_DEPLOYMENT.md for instructions.

• 🔍 Search Listings: Search for active Etsy listings with keyword filtering
• 🏪 Shop Information: Get detailed shop information and listings
• 📦 Product Details: Access listing inventory, images, and variations
• 📊 Trending Data: Retrieve trending listings on Etsy
• ✏️ Create & Update Listings: Post new products and manage existing ones
• 🎨 Manage Shop Sections: Organize your shop with categories
• 🛠️ Full Shop Management: Update shop info, inventory, images, and more
• 🔐 OAuth Support: Secure authenticated access for write operations
• 💬 Smart Prompts: Pre-built prompts for listing creation, SEO optimization, pricing, and analytics
• 📚 Comprehensive Resources: Built-in guides for SEO, photography, shipping, and seller best practices
• 🏷️ Tool Annotations: All 19 tools include readOnlyHint, destructiveHint, and idempotentHint for better AI understanding
• ⚙️ Zero Configuration: Works out-of-the-box with sensible defaults, fully configurable via environment variables
• � Built with Latest MCP Standards: Uses @modelcontextprotocol/sdk v1.0.4

1. Clone this repository:

git clone <your-repo-url>
cd etsy_mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

Deploy to Smithery for hosted, always-available access:

1. Push your code to GitHub
2. Connect to Smithery
3. Click Deploy

📖 Full Guide: See SMITHERY_DEPLOYMENT.md for complete deployment instructions.

Test locally with the Smithery interactive playground:

npm run dev

Or compile TypeScript manually:

npm run compile

1. Visit the Etsy Developer Portal
2. Create a new app or use an existing one
3. Generate an API key (also called "Keystring")
4. For shop management features, set up OAuth 2.0 to get an access token
5. Set up your environment variables (see below)

To create, update, or delete listings and manage your shop, you need an OAuth access token:

1. In the Etsy Developer Portal, configure OAuth redirect URLs
2. Follow the Etsy OAuth 2.0 flow
3. Exchange the authorization code for an access token
4. Add the access token to your environment variables

📖 Detailed Guide: See OAUTH_SETUP.md for complete step-by-step instructions with code examples.

Note: Read-only operations (searching, viewing listings) only require the API key.

The server works out-of-the-box without any configuration. For production use with your own shop, you can set the following environment variables:

ETSY_API_KEY=your_etsy_api_key_here        # Optional: Defaults to demo mode
ETSY_SHOP_ID=your_shop_id                   # Optional: For faster shop operations
ETSY_ACCESS_TOKEN=your_oauth_access_token   # Optional: Required only for write operations

Note:

• Without an API key, the server runs in demo mode for documentation/testing purposes
• Read-only operations (searching, viewing listings) require an API key
• Write operations (creating/updating listings) require both API key and OAuth access token

After deploying to Smithery, use the hosted URL:

{
  "mcpServers": {
    "etsy": {
      "url": "https://server.smithery.ai/your-username/etsy-mcp-server/mcp",
      "config": {
        "apiKey": "your_etsy_api_key",
        "shopId": "your_shop_id",
        "accessToken": "your_oauth_token"
      }
    }
  }
}

Add this server to your Claude Desktop configuration:

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "etsy": {
      "command": "node",
      "args": ["C:\\Users\\Owner\\etsy_mcp\\build\\index.js"],
      "env": {
        "ETSY_API_KEY": "your_etsy_api_key_here",
        "ETSY_ACCESS_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "etsy": {
      "command": "node",
      "args": ["/path/to/etsy_mcp/build/index.js"],
      "env": {
        "ETSY_API_KEY": "your_etsy_api_key_here",
        "ETSY_ACCESS_TOKEN": "your_oauth_token_here"
      }
    }
  }
}

Search for active Etsy listings with keyword filtering.

Parameters:

• keywords (required): Search keywords
• limit: Maximum results (default: 25, max: 100)
• offset: Results to skip for pagination
• min_price: Minimum price filter
• max_price: Maximum price filter
• sort_on: Field to sort by (created, price, updated, score)
• sort_order: Sort direction (asc, desc)

Example:

{
  "keywords": "handmade jewelry",
  "limit": 10,
  "sort_on": "price",
  "sort_order": "asc"
}

Get detailed information about a specific listing.

Parameters:

• listing_id (required): Numeric listing ID
• includes: Array of additional data (Shop, Images, User, Translations, Inventory)

Example:

{
  "listing_id": 1234567890,
  "includes": ["Images", "Shop"]
}

Get information about an Etsy shop.

Parameters:

• shop_id (required): Numeric shop ID

Get all listings from a specific shop.

Parameters:

• shop_id (required): Numeric shop ID
• limit: Maximum results (default: 25)
• offset: Results to skip
• state: Filter by state (active, inactive, sold_out, draft, expired)

Search for Etsy shops by name.

Parameters:

• shop_name (required): Shop name to search
• limit: Maximum results
• offset: Results to skip

Get inventory information including quantities and variations.

Parameters:

• listing_id (required): Numeric listing ID

Get all images for a listing.

Parameters:

• listing_id (required): Numeric listing ID

Get shop sections/categories.

Parameters:

• shop_id (required): Numeric shop ID

Get currently trending listings on Etsy.

Parameters:

• limit: Maximum results (default: 25)
• offset: Results to skip

Find shops by location or other criteria.

Parameters:

• location: Location to search
• limit: Maximum results
• offset: Results to skip

Create a new product listing in your shop.

Parameters:

• shop_id (required): Your shop ID
• quantity (required): Available quantity
• title (required): Listing title (max 140 characters)
• description (required): Item description
• price (required): Price in shop currency
• who_made (required): i_did, someone_else, or collective
• when_made (required): e.g., made_to_order, 2020_2023
• taxonomy_id (required): Category taxonomy ID
• shipping_profile_id: Shipping profile ID (optional)
• shop_section_id: Shop section ID (optional)
• tags: Array of tags, max 13 (optional)

Example:

{
  "shop_id": 12345678,
  "quantity": 10,
  "title": "Handmade Ceramic Mug",
  "description": "Beautiful handcrafted ceramic mug...",
  "price": 25.99,
  "who_made": "i_did",
  "when_made": "made_to_order",
  "taxonomy_id": 1234,
  "tags": ["ceramic", "mug", "handmade", "pottery"]
}

Update an existing listing's details.

Parameters:

• shop_id (required): Your shop ID
• listing_id (required): Listing ID to update
• title: New title
• description: New description
• price: New price
• quantity: New quantity
• tags: New tags array
• shop_section_id: Shop section ID

Example:

{
  "shop_id": 12345678,
  "listing_id": 987654321,
  "price": 29.99,
  "quantity": 15
}

Remove a listing from your shop.

Parameters:

• listing_id (required): Listing ID to delete

Update inventory details including variations, SKUs, and quantities.

Parameters:

• listing_id (required): Listing ID
• products (required): Array of product variations
• price_on_property: Property IDs affecting price
• quantity_on_property: Property IDs affecting quantity
• sku_on_property: Property IDs affecting SKU

Add an image to a listing.

Parameters:

• shop_id (required): Your shop ID
• listing_id (required): Listing ID
• image_url (required): URL of the image
• rank: Display order (1 = primary)
• alt_text: Accessibility text

Create a new section/category in your shop.

Parameters:

• shop_id (required): Your shop ID
• title (required): Section title

Example:

{
  "shop_id": 12345678,
  "title": "Holiday Collection"
}

Update a shop section name.

Parameters:

• shop_id (required): Your shop ID
• shop_section_id (required): Section ID
• title (required): New title

Remove a shop section.

Parameters:

• shop_id (required): Your shop ID
• shop_section_id (required): Section ID to delete

Update shop information and settings.

Parameters:

• shop_id (required): Your shop ID
• title: Shop title
• announcement: Shop announcement message
• sale_message: Message to buyers at checkout
• policy_welcome: Shop policies welcome message

Example:

{
  "shop_id": 12345678,
  "announcement": "Holiday sale - 20% off all items!",
  "sale_message": "Thank you for your purchase!"
}

The server provides comprehensive prompt templates to help you with common Etsy seller tasks:

Complete guide for creating an optimized Etsy listing with best practices.

Arguments:

• product_type (required): Type of product (e.g., handmade, vintage, craft supply)

Provides guidance on:

• Title creation (140 char max, SEO-optimized)
• Description structure and formatting
• Tags strategy (13 tags with keyword research)
• Pricing calculations (materials, labor, fees)
• Photography checklist

Generate SEO-optimized title, tags, and description for existing listings.

Arguments:

• listing_id (required): The listing to optimize
• focus_keywords (optional): Keywords to prioritize

Generates:

• SEO-optimized title variations
• Enhanced description with keyword integration
• 13 strategic tags based on search trends
• Competitive analysis framework
• Action items for improvement

Create comprehensive shop performance analysis template.

Arguments:

• shop_id (required): Shop to analyze
• time_period (optional): Analysis timeframe (e.g., last_month, last_quarter)

Analyzes:

• Traffic metrics and conversion rates
• Sales performance and trends
• SEO effectiveness
• Customer insights and behavior
• Actionable recommendations

Tailored product photography guidance for Etsy.

Arguments:

• product_category (required): Category (jewelry, home decor, clothing, etc.)

Covers:

• Equipment recommendations
• Shot list specific to category
• Lighting setup (natural and artificial)
• Styling and composition tips
• Post-processing techniques
• Etsy-specific best practices

Calculate competitive pricing with full cost analysis.

Arguments:

• material_cost (required): Total material costs
• time_hours (required): Hours to create
• desired_hourly_rate (optional): Preferred hourly rate (default: $25)

Calculates:

• Complete cost breakdown (materials, labor, overhead)
• Etsy fees (transaction, processing, listing)
• Break-even price
• Suggested retail price with profit margin
• Premium positioning options
• Profitability analysis

Example Usage:

Use prompt "pricing-strategy" with:
- material_cost: 15.50
- time_hours: 3
- desired_hourly_rate: 30

The server provides comprehensive documentation and guides as resources:

URI: etsy://docs/api

Complete Etsy Open API v3 reference documentation including:

• Authentication methods (API key, OAuth 2.0)
• Rate limits and best practices
• All endpoint documentation
• Request/response formats
• Error codes and handling

URI: etsy://docs/seller-handbook

Comprehensive seller guide covering:

• Shop setup and configuration
• Listing optimization strategies
• Product photography best practices
• SEO strategies for Etsy search
• Customer service excellence
• Marketing and growth tactics
• Seasonal planning guide

URI: etsy://docs/seo-guide

Complete SEO optimization guide:

• Understanding Etsy search algorithm
• Keyword research methods and tools
• Title optimization formulas
• Tag strategy (maximizing all 13 tags)
• Description SEO techniques
• Category and attribute selection
• Performance tracking and analytics
• A/B testing strategies
• Common SEO mistakes to avoid
• Quick wins checklist

URI: etsy://docs/shipping

Everything about shipping on Etsy:

• Setting up shipping profiles
• Domestic and international shipping
• Free shipping strategies
• Carrier comparisons (USPS, UPS, FedEx)
• Packaging best practices and branding
• Tracking and insurance
• Handling shipping issues
• International customs requirements
• Seasonal shipping preparation

URI: etsy://docs/photography

Professional product photography guide:

• Equipment essentials (cameras, lighting, support)
• Technical requirements for Etsy
• Essential shot list (hero, detail, lifestyle, scale)
• Lighting techniques (natural and artificial)
• Styling and composition rules
• Camera settings (smartphone and DSLR)
• Post-processing workflow
• Category-specific tips (jewelry, clothing, home decor, art)
• Mobile photography best practices
• Video content tips

URI: etsy://tools/fees-calculator

Interactive fees calculator with:

• All Etsy fee structures (listing, transaction, processing, offsite ads)
• Example calculations
• Pricing formulas for profitable pricing
• Tips for managing fee costs
• JSON format for programmatic access

Example Usage:

Read resource "etsy://docs/seo-guide" for complete SEO strategies
Read resource "etsy://tools/fees-calculator" for pricing calculations

# Interactive playground with all tools
npm run dev

npm run compile

npm start

The Etsy API has rate limits. Please refer to Etsy's API documentation for current rate limit information.

This server uses:

• @modelcontextprotocol/sdk: Latest MCP SDK (v1.0.4)
• TypeScript: For type safety
• Axios: For HTTP requests to Etsy API
• Node.js: ES2022 modules

etsy_mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                 # Compiled JavaScript output
├── .github/
│   └── copilot-instructions.md
├── smithery.yaml          # Smithery deployment config
├── package.json
├── tsconfig.json
├── README.md             # Main documentation
├── SMITHERY_DEPLOYMENT.md # Smithery deployment guide
├── OAUTH_SETUP.md        # OAuth setup guide
├── QUICK_REFERENCE.md    # Quick reference guide
├── .env.example          # Environment template
└── .gitignore

The server includes comprehensive error handling:

• API errors return detailed error messages with status codes
• Missing API key throws a descriptive error on startup
• All Axios errors are caught and formatted for easy debugging

Contributions are welcome! Please ensure:

1. TypeScript compiles without errors
2. Follow the existing code style
3. Add appropriate error handling
4. Update documentation for new features

MIT

• � Smithery Deployment Guide - Deploy to hosted infrastructure
• �📖 OAuth Setup Guide - Complete OAuth 2.0 setup instructions
• 📋 Quick Reference - Tool categories and common examples
• Etsy API Documentation
• Model Context Protocol
• MCP SDK Documentation
• Smithery Platform

Make sure you've set the ETSY_API_KEY in your MCP configuration or environment.

Verify your API key is valid and has the necessary permissions in the Etsy Developer Portal.

Ensure your internet connection is working and you can reach openapi.etsy.com.

• 1.2.0: Quality improvements (Smithery score: 69 → 100)
  • ⚙️ Optional Configuration: All config fields now optional with sensible defaults (+15pts)
  • 🏷️ Tool Annotations: Added readOnlyHint, destructiveHint, and idempotentHint to all 19 tools (+9pts)
  • 🎨 Server Icon: Added Etsy-themed SVG icon for better visual identity (+7pts)
  • Zero-config deployment support - server runs without any credentials for demo/testing
  • Environment variable fallbacks for all configuration options
• 1.1.0: Added prompts and resources
  • 5 comprehensive prompts for seller guidance
  • 6 resource guides (SEO, photography, shipping, fees calculator)
  • Enhanced AI assistant capabilities
• 1.0.0: Initial release with 19 Etsy API tools
  • 10 read-only tools for searching and viewing
  • 9 shop management tools for creating and updating
  • Full OAuth support for authenticated operations
  • Create, update, and delete listings
  • Manage shop sections and inventory
  • Upload images and update shop info