Etsy

@pipeworx/etsy

Etsy Open API v3 を使って、有効な Etsy 出品を検索します。API キーだけで認証できる 3 つのエンドポイントに限定しています（OAuth ユーザートークンは不要です）。

Pipeworx の一部です。AI エージェントを 1879 以上のライブデータソースに接続する MCP ゲートウェイです。これは独立した非公式の連携機能であり、上流のプロバイダーとは提携も承認もされておらず、同プロバイダーから公開されたものでもありません。

ツール

• etsy_search_listings(keywords?, limit?, offset?, sort_on?, sort_order?, min_price?, max_price?, taxonomy_id?, buyer_country?) — サイト全体の有効な出品を検索します（findAllListingsActive）。
• etsy_search_shop_listings(shop_id, keywords?, limit?, offset?, sort_on?, sort_order?) — 1 つのショップ内の有効な出品を検索します（findAllActiveListingsByShop）。
• etsy_get_listing(listing_id) — ID で出品を 1 件取得します（getListing）。

販売済み価格や相場データはありません。Etsy の v3 API には存在しません。有効な出品のみが対象です。

認証

BYO キーのみ（_apiKey）に対応し、API キーが必要です。 https://www.etsy.com/developers/register で無料アプリを登録すると、キー文字列と共有シークレットを取得できます。?_apiKey=<keystring> を渡してください。「Your Apps」ページに表示される、コロンで連結した <keystring>:<shared_secret> 形式も受け付けます。パックが形式の違いを処理します（下記の注意点を参照）。

Etsy の v3 リファレンスには、各エンドポイントで必要な認証が記載されています。上記の 3 つのエンドポイントだけが api_key のみで利用できます。それ以外（ショップ／レシート／ユーザーの管理、出品の書き込み）には、Etsy の手動商用審査を経て発行される OAuth ユーザートークンが必要です。このパックの対象外です。Etsy の審査で後日、より広いアクセスが許可された場合は、別のパックを作るのではなく、このパックを拡張してください。

BYO は一時的な対応ではなく、確定した方針です。Bruce は 2026-10-02（フリート #2632）に stop-tracking と判断しました。Pipeworx が Etsy のプラットフォームアプリを登録したり、前面に出したりすることはありません。ゲートウェイマニフェストから、設定されたことのない PLATFORM_ETSY_KEY の宣言は削除されており、再調査も行われていません。 Etsy アプリを登録するには、パスワードで Etsy アカウントにサインインし、その後 Etsy による手動の「Personal Approval」を受ける必要があります。また、審査待ちアプリの 403 は、でっち上げたキーの 403 とバイト単位で同一であるため、待機を終わらせる手段となる調査はありません。キーなしで呼び出すと「requires an API key」と表示され、登録 URL が案内されます。このパックのライブ呼び出しは、承認済みのキーを使って検証されていません。実際に承認されたキー文字列を持つ最初の呼び出し元が、ライブ環境で動作を確認することになります。

データソース

• https://developers.etsy.com/documentation/reference/ — Etsy Open API v3。 ベース URL は https://openapi.etsy.com/v3/application です。

次の担当者向けの注意点：

• Etsy の説明は x-api-key ヘッダーの値について矛盾しており、実験で解決することはできません。 これら 3 つのエンドポイントの api_key リファレンスにはキー文字列のみが記載されていますが、クイックスタートにはコロンで連結した keystring:shared_secret のペアが示されています（これは実際には OAuth トークンエンドポイント用の Basic 認証情報です）。Etsy の Personal Approval を待っているアプリが返す 403 は、でっち上げたキーが返す 403 と バイト単位で同一 です（2026-09-09 にネガティブコントロールで確認済み、フリート #1279）。そのため、有効化前の調査では 2 つのヘッダー形式を判別できません。そこでこのパックはキー文字列を送信し、403 の場合に限り、呼び出し元が渡した元の値で 1 回だけ再試行します。どちらの形式が有効かを示すライブの成功応答が得られるまでは、これを 1 回の呼び出しに「簡素化」しないでください。
• このパックは Etsy のレスポンス JSON を、フィールド名を再マッピングせず、ほぼそのまま返します（count + results と source フィールド）。Listing リソースの正確な形状は、公開された OpenAPI リファレンスでのみ確認されており、認証済みのライブレスポンスでは確認されていないためです（ビルド時に有効なキーがありませんでした。上記の「認証」を参照）。

クイックスタート

MCP クライアント（Claude Desktop、Cursor、Windsurf など）に追加します：

{
  "mcpServers": {
    "etsy": {
      "url": "https://gateway.pipeworx.io/etsy/mcp"
    }
  }
}

このエンドポイントが実際に提供するもの

https://gateway.pipeworx.io/etsy/mcp の tools/list は、上記の表にあるツールに加えて、共有 Pipeworx メタツール（ask_pipeworx、 discover_tools、search_within、remember／recall など、ゲートウェイ全体で使えるツール一式）も返します。そのため、表示されるツール数はこの表より多くなります。現在、単一パックのエンドポイントには、そのパック独自のツールに加えて、共有ツールが約 30 個表示されます。接続の initialize レスポンスに正確な対象範囲が記載されており、その日の状況を確認するための正式な情報源となります。

これは意図的なものであり、誤って多重化されているわけではありません。メタツールを使えば、このパックでは扱えない質問にも、カタログ全体から振り分ける ask_pipeworx を通じて回答できます。MCP サーバーをもう 1 つ追加する必要はありません。現時点では、メタツールなしでパックのエンドポイントをマウントする方法はありません。余分なスキーマによるコンテキスト消費が、ルーティングの利点を上回る場合は、複数のパックエンドポイントではなく、フルゲートウェイに一度だけ接続してください。

または、Pipeworx のフルゲートウェイに接続すると、このパックのツールだけでなく、すべてのパックのツールが直接一覧表示されます。

{
  "mcpServers": {
    "pipeworx": {
      "url": "https://gateway.pipeworx.io/mcp"
    }
  }
}

どちらの URL も、同じゲートウェイと同じ 1879+ 個のデータソースに接続します。異なるのは、どのパックのツールが直接一覧表示されるかだけです。どちらからでも、ask_pipeworx を使ってすべてのツールにアクセスできます。

MCP クライアントがなくても、HTTP 経由で呼び出せます

curl -X POST https://gateway.pipeworx.io/v1/tools/etsy_search_listings \
  -H 'Content-Type: application/json' \
  -d '{"keywords":"vintage brass lamp","limit":10}'

最初の呼び出しにアカウントは必要ありません。ツールを確認するには、GET https://gateway.pipeworx.io/v1/tools/etsy_search_listings を呼び出します。ツールを見つけるには、{"query":"..."} を指定して POST https://gateway.pipeworx.io/v1/tools/search_packs を呼び出します。

スタンドアロン（ゲートウェイアカウント不要）

このパッケージは、ローカルの stdio MCP サーバーとしても実行できます。Pipeworx アカウントもゲートウェイとの往復通信も不要です。

{
  "mcpServers": {
    "etsy": {
      "command": "npx",
      "args": ["-y", "@pipeworx/mcp-etsy"]
    }
  }
}

または、起動を確認するために直接実行します。

npx -y @pipeworx/mcp-etsy

stdin/stdout 経由で MCP を使用し、このパックのツールのみを対象に initialize／tools/list／tools/call に応答します。上記のゲートウェイ接続で追加される共有メタツールは含まれません。同じソース、同じツールで、ask_pipeworx によるルーティングはありません。

ask_pipeworx を使う

ツールを直接呼び出す代わりに、平易な英語で質問できます。上記のパックエンドポイントでも、フルゲートウェイでも利用できます。

ask_pipeworx({ question: "your question about Etsy data" })

ゲートウェイが適切なツールを選び、引数を自動的に設定します。

詳細情報

• ドキュメントとガイド
• pipeworx.io

ライセンス

MIT