Etsy MCP Server

An MCP (Model Context Protocol) server for interacting with the Etsy API. This service handles authentication, API calls to Etsy for managing listings, shop details, shipping profiles, and image uploads.

Overview

This service provides a set of tools accessible via the Model Context Protocol (MCP) to interact with the Etsy V3 API. It manages the OAuth 2.0 authentication flow (including PKCE token refresh), stores tokens securely, and exposes functionalities like creating listings, fetching shop data, managing shipping profiles, and uploading images. The goal is to simplify interactions with the Etsy API for MCP-compatible clients.

This MCP server is primarily designed for development and tool integration. Please ensure you comply with Etsy’s API Terms of Use.

Features

• 🔑 OAuth2 Authentication: Handles the complete Etsy OAuth2 flow with PKCE.
• 🛍️ Listing Management: Create, and retrieve Etsy listings.
• ℹ️ Shop Information: Fetch details for your Etsy shop.
• 📦 Shipping Profiles: List and create shipping profiles for your shop.
• 🖼️ Image Uploads: Upload images and associate them with your listings.
• 🔧 Default Shop Management: Set and get a default shop for easier multi-shop use.
• 🔒 Secure Token Storage: Persists OAuth tokens securely.

Installation

Prerequisites

• Node.js (version 18.0.0 or higher recommended - see package.json engines)
• npm (usually comes with Node.js) or yarn

Manual Installation

1. Clone the repository (replace with your repository URL if you host it on GitHub/GitLab etc.):

   git clone 
   cd etsy-mcp
   

   (If you’re working locally, you can skip the clone and just cd into the project directory.)

2. Install dependencies:

   npm install
   

   Or if you use yarn:

   yarn install
   

3. Configure Environment Variables: Copy the .env.example file to a new file named .env:

   cp .env.example .env
   

   Then, open .env and fill in your Etsy App credentials:

   ETSY_API_KEY=YOUR_ETSY_APP_API_KEY
   ETSY_CLIENT_SECRET=YOUR_ETSY_APP_CLIENT_SECRET
   # Optional: define a specific host and port for the OAuth callback redirect URI
   # ETSY_MCP_HOST=localhost
   # ETSY_MCP_OAUTH_PORT=3003
   # ETSY_MCP_REDIRECT_URI=http://localhost:3003/oauth/callback
   # Optional: define a custom path for token storage and logs
   # ETSY_MCP_TOKEN_PATH=/path/to/your/token_storage_directory
   # ETSY_MCP_LOG_PATH=/path/to/your/logs_directory
   # Optional: Your default shipping profile ID for physical items
   # SHIPPING_PROFILE_ID=YOUR_DEFAULT_SHIPPING_PROFILE_ID
   

   Note: The REDIRECT_URI in your .env file (or the default http://localhost:3003/oauth/callback) must match one of the redirect URIs configured for your Etsy App.

Usage

Run the Service

• For production/built version: