Etsy Seller MCP Hub

Etsy Seller MCP Hub

[CI] [npm] [License: MIT] Official MCP Registry [Glama score]

Open-source MCP server for Etsy sellers. Manage your own Etsy shop's listings, orders, inventory, personalization and media with AI assistants, scripts or local applications. Built on the Etsy Open API v3 with 79 MCP tools, a CLI and a local HTTP gateway.

This is a seller-side shop management toolkit. It does not monitor consumer prices, search for buyer deals or automate shopping.

First-time setup · Security review · Connector troubleshooting · MCP configs · Seller workflows demo · Existing API keys · Hosting and privacy · Roadmap · Glama listing · FAQ · Directories

The term 'Etsy' is a trademark of Etsy, Inc. This Application uses Etsy's API, but is not endorsed or certified by Etsy.

What can sellers do?

• Inspect active listings and inventory; review orders, transactions, shop data and shipping settings.
• Update approved listings, inventory and personalization; upload product images, videos or files.
• Use Etsy's current Open API v3 endpoints through 79 MCP tools, with advanced raw API operations when needed.
• Run the same seller workflows from the etsyctl CLI, local HTTP API or compatible AI clients.

Example prompts: “Which of my active listings have low stock?”, “Show paid but unshipped orders by ID”, “Review the personalization options for listing 123456789”, “Prepare these listing changes for my approval”.

Seller-focused read-only workflows: etsy_report_low_stock (bounded inventory scan) and etsy_report_unshipped (minimized customer data). CLI equivalents: etsyctl report low-stock and etsyctl report unshipped.

Quick start

See the step-by-step guide for Etsy authorization and operating system details.

Requires Node.js 22+ plus an approved Etsy Open API v3 app and authorized credentials.

Install from npm

Install the public package from npm:

npm install -g etsy-seller-mcp-hubetsyctl init --shop-id 12345678    # replace with your actual shop IDetsyctl doctor                    # inspect local config, then enter your own credentials# Complete Etsy OAuth as documented in docs/QUICKSTART.mdetsy-mcp

The npm package is etsy-seller-mcp-hub. For first use, add ETSY_MCP_READ_ONLY=1 in the MCP client config. The installed commands remain etsy-mcp (local MCP server) and etsyctl (CLI).

Run from source

git clone https://github.com/Bl0ck154/etsy-seller-mcp-hub.gitcd etsy-seller-mcp-hubcp config.example.json /tmp/etsy-seller-config.json# Edit shop_id, credential paths, and local backup paths in the copied JSON.export ETSY_HUB_CONFIG=/tmp/etsy-seller-config.jsonnode bin/etsyctl.mjs shopsnode bin/etsy-mcp.mjs

Configuration examples use Linux filesystem locations. Replace them with absolute paths for your computer; never commit keys or tokens. The shops command lists configured shop aliases, whereas live shop operations require OAuth. See credentials.example.json and MCP client setup.

CLI examples

etsyctl --helpetsyctl doctoretsyctl report low-stock --threshold 3 --limit 10 --offset 0etsyctl report unshipped --limit 20 --offset 0

The seller reports are read-only and do not return buyer contact information in the paid/unshipped summary.

Advanced CLI examples

etsyctl listing list active --limit 100etsyctl listing get 1234567890etsyctl inventory get 1234567890etsyctl orders list --limit 20 --paid trueetsyctl personalization get 1234567890etsyctl images list 1234567890etsyctl request GET /application/shops/12345678/sections

Will my old Etsy API key work?

Yes, if it is an existing approved key for Etsy Open API v3 and you have the required OAuth authorization. Etsy's July 2026 Seller App tier is an easier approval path for new shop owners. Etsy explicitly says that sellers who already hold a Personal Key are not eligible for that new tier because their current keys offer comparable access.

MCP adds an interface for AI clients; it does not change Etsy's permissions. We do not operate a shared server that collects other sellers' Etsy tokens. Seller Apps are own-shop only. A developer operating one service for unrelated sellers needs suitable Etsy access (Personal App and potentially Commercial Access) and secure multi-tenant OAuth, which this repository does not currently implement. Each self-hosted user must configure their own authorized credentials.

Read Etsy API access: existing keys, Seller Apps and Commercial Access.

Authentication and security

Etsy v3 requires a keystring and shared secret in the x-api-key header. Access to private seller data or write operations additionally requires OAuth 2.0 scopes. The hub supports OAuth PKCE, refresh, retries and rate limits. To authorize your shop:

etsyctl oauth start --shop main --redirect https://your-registered-callback.example/oauth/callbacketsyctl oauth complete --state STATE --code CODE

The hub verifies ownership of the configured shop after OAuth. Do not copy refresh tokens from other programs that rotate them.

For local HTTP:

ETSY_HUB_CONFIG=/absolute/path/config.json node src/server.mjs

The service binds to 127.0.0.1 by default and refuses external binds without an internal bearer token. For remote use, add authenticated TLS and appropriate access controls. Existing remote MCP OAuth supports a private, owner-approved ChatGPT client, not general third-party seller sign-in.

The public self-hosted MCP exposes 79 tools in full mode. Set ETSY_MCP_READ_ONLY=1 to expose only 53 tools annotated read-only. To enable writes, remove the read-only variable, grant the necessary Etsy OAuth write scopes and reauthorize your own shop. Full-access steps. This is an additional tool filter, not a substitute for Etsy OAuth permissions. Typed listing, inventory and media writes create backups where supported; raw API writes have no automatic snapshots. Confirm any live modification before giving an AI client write access.

Docker

docker build -t etsy-seller-mcp-hub:local .docker run --rm --name etsy-seller-mcp-hub -p 127.0.0.1:3737:3737 -v /absolute/etsy-data:/data:rw -e ETSY_HUB_CONFIG=/data/config.json etsy-seller-mcp-hub:local

Inside Docker, set server.host to 0.0.0.0 and configure a nonempty server.auth_token_file, otherwise startup will reject external binding. Expose the host port only on localhost or behind authenticated HTTPS. The Dockerfile runs as a non-root user.

Development

npm run checknpm testnpm pack --dry-run --ignore-scripts

Tests use mocks and do not write to a live shop. See Contributing, Security and the MIT license.

© 2026 Bl0ck154. Independent open-source software for authorized Etsy seller integrations.

Multipart media uploads are limited to 64 MiB of decoded files per request by default. Configure ETSY_HUB_MAX_UPLOAD_BYTES (bytes, maximum 192 MiB) for larger files. Local file-path multipart uploads now stream in 64 KiB chunks; base64 JSON uploads from remote MCP remain buffered and size-limited.