etsy-mcp
etsy-mcp
Etsy向けの初のプロダクショングレードのModel Context Protocol(MCP)サーバーです。ClaudeをあなたのEtsyショップの出品情報、在庫、注文、統計に接続しましょう。読み取り専用で、5分でセットアップ可能です。
なぜこれが必要なのか
EtsyのOpen API v3は十分に文書化されており安定していますが、ショップにLLMを導入したいすべてのセラーは、毎回同じOAuthとページネーションの処理をゼロから書くことになります。既存のMCP統合は簡易的なデモに過ぎず、トークンのリフレッシュ、リトライロジック、Etsyが実際に要求するショップごとのページネーションが欠けています。
Etsyで販売を行っており、Claude(またはMCP対応のAIアシスタント)に、ショップの内容(何が出品されているか、昨日何が発送されたか、在庫が少なくなっているものは何か)を「ただ知っていてほしい」と思ったことがあるなら、そのギャップこそが「今日の注文を要約して」がそのまま動くか、カスタム統合が必要になるかの違いです。
etsy-mcpはそのギャップを埋めます。これは、8つの読み取り専用EtsyエンドポイントをあらゆるMCPクライアントに公開する、軽量でテスト済みのMITライセンスのMCPサーバーです。長年にわたる大規模なEコマース自動化の運用経験に基づいて構築されています。
Related MCP server: @mcpengine/etsy
何ができるのか
このサーバーをClaude Code、Claude Desktop、または任意のMCPホストに接続し、以下のように質問できます:
「ショップ内でタイトルに
vintageという単語が含まれる出品を検索し、在庫が5個未満のものがいくつあるか教えて。」「昨日の注文数はいくつ?購入者別および合計収益でグループ化して。」
「レシート 5550001 を取得して、どの取引が発送済みで、何が未発送か教えて。」
「過去30日間のショップ統計はどうだった?注文数、お気に入り登録者数、有効な出品数を比較して。」
「出品ID 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 # optionalEtsy 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を再起動します。新しいセッションで8つの 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)ショップ内のすべての有効な出品のページネーション付きダンプです。カタログ全体の推論(「タイトルにキーワードが欠けていないか監査する」など)に役立ちます。1回のツール呼び出しを制限するため、ソフトキャップは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、フォーマッタ、テナントフィンガープリントスクラバー):
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 が読み込まれる前にサーバーが起動しようとしました。親シェルで変数をエクスポートするか、MCPホストの設定の env ブロックにそれらが含まれていることを確認してください。
HTTP 403 (レシート/取引) — リフレッシュトークンのスコープに transactions_r が不足しています。上記の読み取りスコープを指定して再ブートストラップしてください。
データがあるはずなのに結果が空 — shop_id を確認してください。Etsyの /shops/{shop_id}/... エンドポイントは、OAuthトークンが認可されたショップのデータのみを返します。
ページネーションが遅い — Etsyのページサイズ上限はリクエストあたり100であり、当サーバーの制限ではありません。長い期間(長期の注文履歴)の場合、複数回の往復が発生します。limit 引数を下げて呼び出し範囲を制限してください。
コントリビューション
Issueやプルリクエストを歓迎します。以下をお願いします:
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.-