etsy

This Etsy MCP Server provides a set of MCP tools to interact with the Etsy V3 API, including authentication via OAuth2 (PKCE), listing management, shop details retrieval, shipping profile handling, and image uploads. After starting the server, clients can invoke tools such as authenticate() to begin the OAuth flow, set_default_shop() to select a default shop, get_listings() to fetch current listings, get_shop_details() to retrieve shop data, and actions to manage shipping profiles and upload images. The server exposes these capabilities over the MCP interface so tools and automation can manage Etsy data without direct API calls.

To use it from an MCP client (for example Cursor IDE), configure the server with the command npm run dev (or npm start for production) and supply necessary environment variables like ETSY_API_KEY and ETSY_CLIENT_SECRET. You will typically authenticate first, then set a default shop, after which most tools will operate against that shop unless you explicitly provide a shop_id. Ensure your redirect URI matches what you configured in your Etsy app and that your tokens are stored securely as configured by the server.

Prerequisites

• Node.js 18.0.0 or higher
• npm (comes with Node.js) or yarn

Manual Installation

1. Clone the repository and navigate to the project directory:

git clone <your-repository-url>
cd etsy-mcp

2. Install dependencies:

npm install

Or with yarn:

yarn install

3. Configure environment variables: Copy the example env file and fill in credentials:

cp .env.example .env

Then edit .env to include:

ETSY_API_KEY=YOUR_ETSY_APP_API_KEY
ETSY_CLIENT_SECRET=YOUR_ETSY_APP_CLIENT_SECRET
# Optional: override host/port for OAuth callback
# ETSY_MCP_HOST=localhost
# ETSY_MCP_OAUTH_PORT=3003
# ETSY_MCP_REDIRECT_URI=http://localhost:3003/oauth/callback
# Optional: token/log paths
# ETSY_MCP_TOKEN_PATH=/path/to/tokens
# ETSY_MCP_LOG_PATH=/path/to/logs
# Optional: default shipping profile
# SHIPPING_PROFILE_ID=YOUR_DEFAULT_SHIPPING_PROFILE_ID

Note: The REDIRECT_URI must match one of your Etsy app's configured redirect URIs.

4. Run the service in development or production mode:

# Development with auto-reload
npm run dev

To run in production (build first):

npm run build
npm start

5. Verify the server starts and listens for MCP commands. You can then connect with an MCP client and begin authentication and data operations.

Environment and configuration tips:

• Keep ETSY_API_KEY and ETSY_CLIENT_SECRET secure; prefer loading them from the server's .env file rather than overriding in client configs.
• Ensure your OAuth Redirect URI matches what Etsy has registered for your app.
• If you enable custom token storage or logs via ETSY_MCP_TOKEN_PATH or ETSY_MCP_LOG_PATH, ensure the directories exist and are writable by the process.
• When using a default shipping profile, provide SHIPPING_PROFILE_ID to automatically apply during relevant operations, but you can override it per request if supported by the client.
• If you encounter token refresh issues, confirm PKCE flow is correctly configured and that the client secret is only used in secure server-side contexts.
• For production deployments, consider containerization (e.g., docker) and securing secrets with env management systems.