etsy-mcp
etsy-mcp
第一个用于 Etsy 的生产级模型上下文协议 (MCP) 服务器。在五分钟内将 Claude 连接到您的 Etsy 店铺商品、库存、订单和统计信息 —— 仅限读取。
为什么会有这个项目
Etsy 的 Open API v3 文档齐全且稳定,但每个想要在店铺之上使用 LLM 的卖家最终都要从零开始编写相同的 OAuth 和分页逻辑。现有的 MCP 集成大多是简单的演示,缺少令牌刷新、重试逻辑以及 Etsy 实际要求的按店铺分页功能。
如果您在 Etsy 上销售,并且希望 Claude(或任何支持 MCP 的 AI 助手)能够直接了解您店铺的情况 —— 比如有哪些商品、昨天发了什么货、哪些库存不足 —— 那么这个差距就是“开箱即用地总结今日订单”与“需要自定义集成才能总结今日订单”之间的区别。
etsy-mcp 填补了这一空白。它是一个轻量级、经过充分测试且采用 MIT 许可的 MCP 服务器,向任何 MCP 客户端公开了八个只读的 Etsy 端点。它基于多年大规模运行电子商务自动化的经验构建。
Related MCP server: @mcpengine/etsy
您可以用它做什么
将此服务器连接到 Claude Code、Claude Desktop 或任何 MCP 主机,然后询问如下问题:
“在我的店铺中搜索标题中带有
vintage字样的商品,并告诉我哪些库存少于 5 件。”“我昨天收到了多少订单?按买家和总收入分组。”
“拉取收据 5550001,告诉我哪些交易已发货,还有哪些尚未发货。”
“过去 30 天我的店铺统计数据如何?比较订单、收藏者和在售商品数量。”
“对于商品 1234567890,向我展示每一个变体、其 SKU 和当前数量。”
Claude 直接读取您的店铺。无需复制粘贴,无需电子表格,无需自定义流水线。
工具 (v0.1,均为只读)
工具 | 功能 |
| 在在售商品中进行关键词搜索,可选择店铺范围。 |
| 通过 ID 获取单个商品。 |
| 获取店铺记录(名称、货币、计数、休假状态等)。 |
| 列出指定日期窗口内一个店铺的收据(订单)。 |
| 通过 ID 获取单个收据,包括行项目交易。 |
| 获取商品的变体级库存(SKU、数量、价格)。 |
| 组合周期汇总:订单、收藏者、收入、商品。 |
| 店铺中所有在售商品的分页列表。 |
写入端点(创建草稿商品、更新库存、标记收据已发货)在 v0.1 中特意未包含。一旦只读功能稳定,计划在 v0.2 中加入。
安装
pip install etsy-mcpv0.1 从此仓库发布。PyPI 发布正在进行中 —— 目前,请使用
pip install git+https://github.com/alveyautomation/etsy-mcp安装,或克隆并在本地运行pip install -e .。
配置凭据
服务器从环境变量中读取所有内容。将 .env.example 复制到 .env 并填写您的租户信息:
ETSY_API_URL=https://api.etsy.com/v3/application/ # default; usually leave alone
ETSY_API_KEY=your-keystring-from-etsy-developers
ETSY_REFRESH_TOKEN=oauth2-refresh-token-for-your-shop
ETSY_DEFAULT_SHOP_ID= # optional fallback
ETSY_HTTP_TIMEOUT=60 # optional, seconds
ETSY_MAX_RETRIES=3 # optional获取 Etsy API 密钥
访问 https://www.etsy.com/developers/your-apps 并注册一个应用。
复制 Keystring —— 这就是
ETSY_API_KEY。为您的一次性 OAuth 引导配置重定向 URI(例如
http://localhost:3000/callback)。
获取刷新令牌
Etsy 使用 带有 PKCE 的 OAuth 2.0。要进行引导,请使用以下参数运行一次标准的 OAuth-PKCE 流程:
response_type=codeclient_id=<您的 keystring>redirect_uri=<您注册的 URI>scope=listings_r shops_r transactions_r(只读 —— 这是此服务器所需的最低权限)state=<随机字符串>code_challenge=<PKCE>和code_challenge_method=S256
将生成的授权码在 POST https://api.etsy.com/v3/public/oauth/token 处交换以获取访问令牌 + 刷新令牌。将 刷新令牌 保存为 ETSY_REFRESH_TOKEN。服务器将自动使用它来生成短期的访问令牌。
使用最小权限的只读令牌。 v0.1 仅调用
GET端点,但纵深防御意味着您永远不应授予服务器刷新令牌写入权限 (*_w)。当 v0.2 推出写入工具时,通过生成一个新的更高权限令牌来选择加入 —— 永远不要反过来操作。
连接到 Claude Code
添加到 ~/.claude/claude_code_config.json(或您项目的 MCP 配置):
{
"mcpServers": {
"etsy": {
"command": "etsy-mcp",
"env": {
"ETSY_API_KEY": "your-keystring",
"ETSY_REFRESH_TOKEN": "your-refresh-token",
"ETSY_DEFAULT_SHOP_ID": "12345678"
}
}
}
}重启 Claude Code。八个 etsy_* 工具将出现在任何新会话中。
连接到 Claude Desktop
编辑 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 或 %APPDATA%\Claude\claude_desktop_config.json (Windows),并添加与上述相同的 mcpServers 块。重启桌面应用。
工具参考
每个工具都返回一个 JSON 信封:
{ "ok": true, "data": { ... } }
{ "ok": false, "error": "human-readable message" }etsy_search_listings
etsy_search_listings(
query: str, # required
shop_id: int | None = None, # scope to a single shop
limit: int = 50, # max 100 (Etsy server cap)
)当提供 shop_id 时,它会访问 /shops/{shop_id}/listings/active。否则,它会访问全局 /listings/active 索引。
etsy_get_listing
etsy_get_listing(listing_id: int)返回商品记录,如果 404 则返回 data: null。
etsy_get_shop
etsy_get_shop(shop_id: int)店铺记录包括 shop_name、currency_code、listing_active_count、num_favorers、is_vacation 等。
etsy_search_orders
etsy_search_orders(
date_from: str, # ISO date "YYYY-MM-DD"
date_to: str, # ISO date "YYYY-MM-DD"
shop_id: int | None = None, # falls back to default
status: str | None = None, # 'open' | 'unshipped' | 'completed' | 'all'
limit: int = 200, # max 1000
)Etsy 将页面大小限制为 100;分页是透明的。当 limit 是截断点时,响应包含 limit_reached: true。
etsy_get_order
etsy_get_order(receipt_id: int, shop_id: int | None = None)返回完整收据(包含 transactions[]),如果 404 则返回 data: null。
etsy_get_inventory
etsy_get_inventory(listing_id: int)返回包含 sku、property_values 和 offerings[](数量、价格、启用状态)的 products[]。使用 offering 数量作为每个变体的规范“可售数量”。
etsy_get_shop_stats
etsy_get_shop_stats(shop_id: int, period: str = "30d")一个组合汇总。Etsy 在 v3 中没有公开一流的 shop/stats 端点,因此这是从店铺记录(收藏者、在售商品数量)和窗口内的收据中合成的。返回形状:
{
"shop_id": 12345678,
"period": "30d",
"period_days": 30,
"date_from": "2026-03-27",
"date_to": "2026-04-26",
"favorers": 314,
"active_listings": 87,
"orders": 42,
"revenue_minor_units": 152400,
"currency_code": "USD"
}period 接受 <N>d 格式,最多 365 天。
etsy_get_active_listings
etsy_get_active_listings(shop_id: int, limit: int = 200)店铺中所有在售商品的分页转储。对于全目录推理(“审计我的标题中缺失的关键词”)很有用。软上限为 1000,以保持单次工具调用的边界。
本地开发
git clone https://github.com/alveyautomation/etsy-mcp
cd etsy-mcp
python -m venv .venv && source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[dev]"
pytest # 49 tests, ~3s预提交钩子(gitleaks, trufflehog, ruff, formatter, 租户指纹清理器):
pip install pre-commit
pre-commit install针对真实 Etsy 沙盒的集成测试受 ETSY_INTEGRATION_TESTS=1 控制。正常贡献不需要它们。
故障排除
Failed to refresh Etsy access token —— 您的刷新令牌已过期或被撤销。Etsy 刷新令牌自签发之日起 90 天内有效,但前提是必须定期使用。重新运行 OAuth-PKCE 引导以生成新的令牌。
Missing required environment variables —— 服务器在加载 .env 之前尝试启动。请在父 shell 中导出变量,或确保您的 MCP 主机配置在 env 块中包含了它们。
HTTP 403 on receipts/transactions —— 刷新令牌的范围缺少 transactions_r。使用上述列出的只读范围重新引导。
Empty results despite known data —— 确认 shop_id。Etsy 的 /shops/{shop_id}/... 端点仅返回 OAuth 令牌已授权的店铺的数据。
Pagination feels slow —— Etsy 将每个请求的页面大小限制为 100,而不是我们。对于较大的日期窗口(长订单历史记录),预计会有多次往返。降低 limit 参数以限制调用。
贡献
欢迎提交问题和拉取请求。请:
在打开 PR 之前运行
pytest(pip install -e ".[dev]")。运行
pre-commit run --all-files。将 v0.1 的新增内容保持在只读范围内。写入端点将在 v0.2 中加入。
测试中仅使用合成数据 —— 不要使用真实的店铺名称、商品 ID 或收据编号。
许可证
MIT —— 参见 LICENSE。
免责声明
etsy-mcp 是一个非官方的第三方集成。它未得到 Etsy, Inc. 的认可、关联或支持。“Etsy”是 Etsy, Inc. 的商标。使用风险自负;在依赖它进行生产决策之前,请先针对您的店铺验证其行为。
Available Tools
8 toolsetsy_get_active_listingsA
List active listings for a shop, paginating transparently.
Args: shop_id: Etsy ShopID. limit: Soft cap on yielded listings (default 200, max 1000).
Returns:
JSON envelope. data.listings is the list of active-listing records.
Inputs: shop_id (required), limit. Returns: result
etsy_get_inventoryA
Fetch the current inventory record (variations + offerings) for a listing.
Args: listing_id: Etsy ListingID.
Returns:
JSON envelope. data is the inventory record (with products[]
carrying property values, SKU, price, and offerings[] with
quantity), or null if absent.
Inputs: listing_id (required). Returns: result
etsy_get_listingA
Fetch the full record for a single listing.
Args: listing_id: Etsy ListingID (integer).
Returns:
JSON envelope. data is the listing record, or null if not found.
Inputs: listing_id (required). Returns: result
etsy_get_orderB
Fetch full receipt (order) detail including transactions.
Args: receipt_id: Etsy ReceiptID (integer). shop_id: Etsy ShopID. Falls back to ETSY_DEFAULT_SHOP_ID if omitted.
Returns:
JSON envelope. data is the receipt record, or null if missing.
Inputs: receipt_id (required), shop_id. Returns: result
etsy_get_shopA
Fetch the shop record for a single shop.
Args: shop_id: Etsy ShopID (integer).
Returns:
JSON envelope. data is the shop record (with name, currency_code,
listing_active_count, num_favorers, etc.), or null if not found.
Inputs: shop_id (required). Returns: result
etsy_get_shop_statsA
Return aggregated stats (orders, favorers, active listings, revenue) for a shop over the given period.
Args: shop_id: Etsy ShopID. period: Lookback window in the form 'd', e.g. '7d', '30d', '90d'. Maximum 365 days.
Returns:
JSON envelope. data is a dict with orders, favorers,
active_listings, revenue_minor_units, currency_code, and
the resolved date_from / date_to.
Inputs: shop_id (required), period. Returns: result
etsy_search_listingsA
Search active Etsy listings by keyword.
Args: query: Free-text keyword search across listing title and tags. shop_id: Optional Etsy ShopID to scope the search to a single shop. When omitted, queries the global active-listings index. limit: Cap on returned results (max 100 enforced by Etsy).
Returns: JSON envelope: {"ok": true, "data": {"results": [...], "count": N}}.
Inputs: query (required), shop_id, limit. Returns: result
etsy_search_ordersA
Search receipts (orders) created in the inclusive [date_from, date_to] window for a shop.
Args: date_from: ISO date (YYYY-MM-DD), start of window. date_to: ISO date (YYYY-MM-DD), end of window. shop_id: Etsy ShopID to scope the search to. Falls back to ETSY_DEFAULT_SHOP_ID if omitted. status: Optional receipt status filter ('open', 'unshipped', 'unpaid', 'completed', 'processing', 'all'). limit: Cap on yielded receipts (default 200, max 1000). Etsy caps page size at 100 per request; pagination is handled transparently.
Returns:
JSON envelope. data.orders is the list of receipt records.
Inputs: date_from (required), date_to (required), shop_id, status, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource (listings, inventory, shop, orders) and operation (get, search, stats), with no overlapping purposes.
All tools follow the consistent pattern 'etsy_<verb>_<noun>', using snake_case and clear verbs (get, search) throughout.
8 tools is reasonable for an Etsy API wrapper, covering key read operations without being excessive.
The server provides only read/search operations; missing critical mutation tools like create/update/delete listing or update order, leaving significant gaps for full lifecycle management.
Maintenance
Related MCP Connectors
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Hosted MCP server for 3Dsellers, the multichannel selling platform. Connect Claude, ChatGPT, Cursor, VS Code or any MCP client and manage your eBay, Amazon, Walmart, Etsy, Shopify, WooCommerce and TikTok Shop stores in plain language: search and update products, publish listings, sync inventory, tag and track orders, run bulk actions and CSV imports, and reply to customer messages. 120+ tools. Sign in with OAuth or a personal token. No eBay developer account and nothing to install. Setup guides and config examples for every client: https://github.com/3dsellers/ebay-mcp-server
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Hosted MCP server to manage a restaurant menu from AI agents - 39 tools over the DuckHub API.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceThis is a deployable remote MCP server that lets OpenAI Agent Builder connect directly to Etsy using Etsy OAuth 2.0 with PKCE.-
- AlicenseCqualityDmaintenanceComprehensive MCP server for the Etsy API v3, providing 50+ tools to manage listings, shops, orders, payments, and more through natural language.1004MIT
- AlicenseAqualityDmaintenanceA full-featured MCP server for the Etsy Open API v3 that enables managing an Etsy shop, including listings, inventory, images, digital files, and orders, through Claude or any MCP-compatible client.262MIT
- FlicenseNot gradedqualityDmaintenanceA custom MCP server exposing database, ticketing, and external-API tools to both Claude Desktop and a self-built autonomous agent powered by Groq's free-tier LLaMA 3.3.-