Skip to main content
Glama

etsy-mcp

Etsy向けの初のプロダクショングレードのModel Context Protocol(MCP)サーバーです。ClaudeをあなたのEtsyショップの出品情報、在庫、注文、統計に接続しましょう。読み取り専用で、5分でセットアップ可能です。

License: MIT Python 3.10+ MCP

なぜこれが必要なのか

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, すべて読み取り専用)

ツール

機能

etsy_search_listings

有効な出品全体からキーワード検索(ショップ指定可能)。

etsy_get_listing

IDを指定して出品情報を取得。

etsy_get_shop

ショップレコード(名前、通貨、件数、休暇設定など)を取得。

etsy_search_orders

指定期間内のレシート(注文)リストを取得。

etsy_get_order

IDを指定してレシートを取得(明細取引を含む)。

etsy_get_inventory

出品ごとのバリエーションレベルの在庫(SKU、数量、価格)を取得。

etsy_get_shop_stats

期間ごとの集計:注文数、お気に入り登録者数、収益、出品数。

etsy_get_active_listings

ショップ内のすべての有効な出品をページネーション付きで取得。

書き込みエンドポイント(下書き作成、在庫更新、発送済みマークなど)は、意図的にv0.1には含まれていません。読み取り専用の操作性が安定した後にv0.2で計画されています。

インストール

pip install etsy-mcp

v0.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キーの取得

  1. https://www.etsy.com/developers/your-apps にアクセスしてアプリを登録します。

  2. Keystring をコピーします。これが ETSY_API_KEY になります。

  3. 一回限りのOAuthブートストラップ用のリダイレクトURI(例: http://localhost:3000/callback)を構成します。

リフレッシュトークンの取得

Etsyは PKCE付きOAuth 2.0 を使用します。ブートストラップのために、以下のパラメータで標準的なOAuth-PKCEフローを一度実行してください:

  • response_type=code

  • client_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 tools
etsy_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

    A3.8/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource (listings, inventory, shop, orders) and operation (get, search, stats), with no overlapping purposes.

    Naming Consistency5/5

    All tools follow the consistent pattern 'etsy_<verb>_<noun>', using snake_case and clear verbs (get, search) throughout.

    Tool Count4/5

    8 tools is reasonable for an Etsy API wrapper, covering key read operations without being excessive.

    Completeness2/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A 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.
      26
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -