- aserper/etsy-mcp exposes 40 tools covering listings, orders, shipping, inventory, payments, taxonomy, and return policies against a real Etsy shop.
- The OAuth client requests all 20 Etsy Open API scopes by default — including listings_d, billing_r, cart_w, favorites_w, recommend_w — while no cart, favorites, recommend, or billing tool is registered (src/index.ts:24-30, 50-53, 8-19).
- Etsy's own first-party Dev MCP server (mcp.api.etsycloud.com/mcp) states it 'does not call the Etsy API directly' — it teaches the API spec and operates no shop.
- Listings can only be created as drafts via create_draft_listing; there is no direct publish tool.
- The repo shows 3 stars, 3 forks, 0 open issues, MIT licence, and a last default-branch commit of 2026-04-02 as of the 2026-07-29 read.
01 What etsy-mcp (aserper) is and who ships it
If you need an AI assistant to actually run an Etsy shop — list products, manage orders, adjust inventory — the server to install is etsy-mcp, a community project by Amit Serper (aserper). Its OAuth flow requests all 20 Etsy Open API v3 scopes by default — including listings_d, billing_r, cart_w, favorites_w, and recommend_w — even though the server registers no cart, favorites, recommend, or billing tool at all (src/index.ts:24-30, 50-53, 8-19).
That's not Etsy's own first-party Dev MCP server, which explicitly does not touch a real shop at all. Etsy documents its own server at developers.etsy.com/documentation/mcp_server/devmcpserver (endpoint https://mcp.api.etsycloud.com/mcp) and states in its own words that it "does not call the Etsy API directly" — it exists only to teach an assistant the shape of the Etsy Open API v3 spec. aserper/etsy-mcp is the opposite: 40 tools that call the real API against a real shop, authenticated with OAuth2.
etsy-mcp is unaffiliated with Etsy — a community server hosted at github.com/aserper/etsy-mcp, licensed MIT. Public record and source read on 2026-07-29 shows the repository at 3 stars, 3 forks, 0 open issues, with a last commit to the default branch on 2026-04-02. The repo's own GitHub description states "37 tools for listings, orders, shipping, reviews, inventory, payments, and more" — but the project's enumerated tool list, read directly, contains 40 named tools, not 37. That's a real discrepancy between the repo's own marketing string and its actual registered surface, and it's worth knowing before you count on either number.
02 Tools it exposes
The 40 tools below come from the source's tool registration, grouped by the modules listed at src/index.ts:8-19 — listings, shop, orders, transactions, shipping, reviews, users, taxonomy, images, inventory, payments, and return-policies.
| Tool | What it does | Read/write |
|---|---|---|
| search_listings | Search listings | Read |
| get_listing | Fetch a single listing | Read |
| create_draft_listing | Create a listing as a draft | Write |
| update_listing | Update an existing listing | Write |
| delete_listing | Delete a listing | Write |
| get_listings_by_shop | List a shop's listings | Read |
| get_listing_images | Fetch listing images | Read |
| upload_listing_image | Upload a listing image | Write |
| upload_listing_video | Upload a listing video | Write |
| delete_listing_image | Delete a listing image | Write |
| get_listing_inventory | Fetch inventory for a listing | Read |
| update_listing_inventory | Update inventory for a listing | Write |
| get_shop | Fetch shop details | Read |
| update_shop | Update shop details | Write |
| find_shops | Search for shops | Read |
| get_shop_sections | Fetch shop sections | Read |
| manage_shop_sections | Create/update/delete shop sections | Write |
| get_shop_receipts | Fetch a shop's receipts | Read |
| get_receipt | Fetch a single receipt | Read |
| update_receipt | Update a receipt | Write |
| create_shipment | Create a shipment | Write |
| get_transactions_by_shop | Fetch a shop's transactions | Read |
| get_transaction | Fetch a single transaction | Read |
| get_transactions_by_receipt | Fetch transactions for a receipt | Read |
| get_shipping_profiles | Fetch shipping profiles | Read |
| create_shipping_profile | Create a shipping profile | Write |
| update_shipping_profile | Update a shipping profile | Write |
| manage_shipping_destinations | Manage shipping destinations | Write |
| get_shipping_carriers | Fetch shipping carriers | Read |
| get_reviews_by_listing | Fetch reviews for a listing | Read |
| get_reviews_by_shop | Fetch reviews for a shop | Read |
| get_me | Fetch the authenticated user | Read |
| get_user | Fetch a user | Read |
| get_user_addresses | Fetch a user's addresses | Read |
| get_buyer_taxonomy | Fetch buyer taxonomy | Read |
| get_taxonomy_properties | Fetch taxonomy properties | Read |
| get_payments | Fetch payments | Read |
| get_ledger_entries | Fetch ledger entries | Read |
| get_return_policies | Fetch return policies | Read |
| manage_return_policy | Create/update a return policy | Write |
That's full Open API v3 coverage including the parts most integrations skip — buyer taxonomy, ledger entries, and return policies — alongside the ordinary listings/shop/orders surface.
03 Install and auth
Transport is stdio. No published Docker image tag is provided in the repository; build the image from source: docker run --rm (image built from repo).
docker run --rm (image built from repo)Auth is OAuth2 against Etsy Open API v3 OAuth2 scopes. The default scope set is not a short, task-scoped list — it's all 20 Etsy Open API scopes, requested automatically unless overridden (src/index.ts:24-30, 50-53). More on why that matters below.
04 What the source shows
Public record and source read on 2026-07-29 turns up the fact that carries this page: the OAuth client requests all 20 Etsy Open API scopes by default — including listings_d (delete), billing_r, email_r, profile_w, cart_r, cart_w, favorites_r, favorites_w, recommend_r, and recommend_w — even though the server registers no cart, favorites, recommendation, or billing tool at all. src/index.ts:24-30 defines a 20-entry ALL_SCOPES constant, and :50-53 passes scopes: config.scopes ?? ALL_SCOPES to the OAuth client by default. The registered tool modules, listed at src/index.ts:8-19, cover listings, shop, orders, transactions, shipping, reviews, users, taxonomy, images, inventory, payments, and return-policies — nothing more. The practical result: the consent screen a shop owner signs grants materially more access than the 40 tools can ever exercise.
Two more things the source shows that the README doesn't spell out. The refresh token is persisted to ~/.etsy-mcp/tokens.json, written with file mode 0o600 (src/index.ts:45-47, src/auth/token-store.ts:23-24) — a point in the server's favor, since a locked-down token file limits blast radius if the host is compromised. And the HTTP client self-throttles outbound calls to 10 requests per second via a 100ms minimum interval between requests, retrying once after a 401 by refreshing the token (src/client/etsy-client.ts:19, :100-110).
05 Quirks, gaps and the honest verdict
- Draft-only listing creation —
create_draft_listingis the only listing-creation tool in the 40-tool set; there is no direct publish tool, so shipping a live listing still requires a separate step outside this server. - Low adoption — 3 GitHub stars and 3 forks as of the 2026-07-29 read, despite a 40-tool surface covering nearly the entire Open API v3. Unproven at scale.
- Self-reported tool count disagrees with itself — the GitHub repo's own description says "37 tools," while the enumerated tool list read directly from the record contains 40 named tools. The two numbers come from the same project and don't match.
- Wrong pick if you're only trying to teach an assistant the API shape — for that, Etsy's own Dev MCP server at
https://mcp.api.etsycloud.com/mcpis the right tool: it needs no API key and, in its own words, "does not call the Etsy API directly." Its docs page states it provides "five tools," though the table beneath that line actually lists seven:learn_etsy_api,search_etsy_api,list_endpoints,get_endpoint,get_schema,list_guides,get_guide.
The verdict: pick aserper/etsy-mcp to operate a real Etsy shop through 40 tools spanning listings, orders, shipping, and inventory. Unless you only want an assistant that understands the Etsy Open API v3 spec well enough to help you build against it — then Etsy's own Dev MCP server is the right, and simpler, tool, since it needs no shop and no OAuth grant at all.
07 Frequently asked questions
- Is aserper/etsy-mcp an official Etsy product?
- No. It's a community project by Amit Serper, unaffiliated with Etsy, licensed MIT. Etsy's own first-party MCP server is a separate, spec-teaching product documented at developers.etsy.com/documentation/mcp_server/devmcpserver.
- What transport does aserper/etsy-mcp use?
- stdio, per the curated record's install configuration.
- Does aserper/etsy-mcp let an assistant publish a live Etsy listing?
- Not directly. Its listing-creation tool is create_draft_listing, and the 40-tool set has no separate publish tool.
- Why would I use Etsy's own Dev MCP server instead?
- If you only need an assistant to understand the Etsy Open API v3 spec — its docs state it 'does not call the Etsy API directly' — that server needs no OAuth grant and no shop at all.
- What OAuth scopes does aserper/etsy-mcp request by default?
- All 20 Etsy Open API scopes via its ALL_SCOPES constant (src/index.ts:24-30), including listings_d, billing_r, email_r, cart_w, favorites_w and recommend_w, even though no cart, favorites, recommend, or billing tool is registered.