etsy

This Etsy MCP Server exposes a subset of the Etsy API through the Model Context Protocol, allowing MCP clients to query shop data, retrieve listings, and perform draft listing operations via tools. The available tools include getShop, getMe, getListingsByShop, createDraftListing, uploadListingImage (placeholder), updateListing, getShopReceipts, getShopSections, getShopSection, getSellerTaxonomyNodes, and getPropertiesByTaxonomyId. Each tool corresponds to Etsy API capabilities and is designed to be invoked by MCP clients to fetch data or perform actions using the authenticated Etsy account.

To use it, configure your MCP client to launch the Etsy MCP Server using the provided command (via npx in your environment) and supply credentials either through environment variables or a local settings file named etsy_mcp_settings.json. The server communicates over stdio, so your MCP client should pipe JSON-RPC messages to stdin and read responses from stdout. For testing, you can send sample MCP messages to verify tool responses, or use the MCP Inspector in development workflows. Authentication requires an Etsy API key, a shared secret, and a refresh token, which the server uses to obtain access to Etsy on behalf of the authenticated user.

Prerequisites:

• Node.js (and npm) installed on your machine
• Git (optional, if cloning the repo)

Step 1: Install dependencies

npm install

Step 2: Build the server (for development builds)

npm run build

Step 3: Start the server locally

npm start

Step 4: Optional - test with MCP Inspector or an MCP client

• You can connect via MCP clients that support stdio. The server will wait for MCP protocol messages on stdin and respond on stdout.
• For testing, you can send a sample JSON-RPC payload through a pipe to the running process or use the built-in inspector script if provided by the project.

Configuration file location (local development): place etsy_mcp_settings.json in the project root (same level as package.json). The server will automatically detect and load it when available.

Notes and tips:

• Credentials can be provided in two ways: environment variables (ETSY_API_KEY, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN) or via the etsy_mcp_settings.json settings file.
• If you generate a refresh token, the helper script npx tsx src/get-refresh-token --keystring YOUR_KEY --shared-secret YOUR_SECRET will open a browser for authentication and print the token.
• The server is designed to exit after a short idle period when no MCP client connects. This is expected behavior for containerized or ephemeral deployments.
• When running with Docker, you can mount your etsy_mcp_settings.json file or supply environment variables. Ensure the file path inside the container matches the mounted location.
• If you encounter issues, check logs for missing credentials or misconfigured paths, and ensure the settings file contains valid Etsy credentials.