etsy-mcp-server

ローカル Etsy MCP サーバー

ローカルの stdio MCP サーバーを介して、AI クライアントを Etsy ショップに接続します。ツールはショップと出品情報を読み取ります。出品の変更、注文の処理、メッセージの送信はできません。Etsy アプリの認証情報と OAuth トークンは、オペレーティングシステムの認証情報ストアに保存されます。

コンピューターの準備

• npm を含む Node.js 24 以降をインストールします。node --version と npm --version で確認してください。
• Etsy の開発者アプリのキー文字列と共有シークレットを取得します。アプリの承認を受けている必要があります。
• 必要に応じて、Etsy アプリに http://localhost:3030/oauth/redirect を登録します。Etsy クイックスタートでは、localhost コールバックの例を紹介しています。認証ガイドでは、HTTPS コールバックについても説明しています。Etsy がアプリのローカルコールバックを拒否した場合、認証情報は保存されず、セットアップは停止します。
• Windows では、資格情報マネージャーを利用できる状態で、セットアップと AI クライアントを同じ Windows アカウントで実行します。
• macOS では、ログインキーチェーンのロックを解除し、AI クライアントと同じアカウントでセットアップを実行します。
• Linux では、GNOME Keyring や KeePassXC など、ロックが解除され、同じデスクトップ D-Bus セッションからアクセスできる Secret Service 実装を使用します。平文保存や Linux カーネルキーリングへのフォールバックはありません。

WSL ディストリビューション、コンテナー、リモート開発ホスト、ネイティブデスクトップは、それぞれ別の実行環境です。Windows 資格情報マネージャーに保存された接続は、WSL 内では自動的に利用できません。セットアップと MCP プロセスは、同じ環境とアカウントで実行してください。

ローカル OAuth API に渡すカスタムコールバック URI は、ループバック HTTP（localhost、127.0.0.1、または [::1]）と、1～65535 の明示的なポートを使用する必要があります。サポート対象外のコールバックは、ブラウザーを開く前に拒否されます。

ショップを接続する

macOS または Linux のローカルの対話型ターミナルで、次のコマンドを実行します。

npx --yes @profplum700/etsy-mcp-server@latest setup

Windows では、PowerShell で次を実行します。明示的に .cmd を指定すると、npm の shim に対する PowerShell のスクリプト実行ポリシー制限を回避できます。

npx.cmd --yes @profplum700/etsy-mcp-server@latest setup

非表示の入力プロンプトにキー文字列と共有シークレットを入力します。これらを AI チャット、設定ファイル、環境変数、コマンド引数に貼り付けないでください。セットアップは Etsy を開き、shops_r と listings_r の権限だけを要求します。認証情報を OS の認証情報ストアに保存する前に、ショップを検証します。

セットアップ時に Codex への登録を求められた場合、それが使用するクライアントである場合に限り「はい」を選択します。それ以外の場合は「いいえ」を選択し、以下の該当するセクションに従ってください。クライアントへの登録によって Etsy のセットアップが置き換えられることはありません。

例では npm の latest リリースを使用します。アップグレードを管理する場合は、セットアップとクライアント設定の両方で @latest を正確な公開済みバージョンに置き換えてください。ソースのチェックアウトやマージされていない PR には、npm でまだリリースされていない機能が含まれている場合があります。

AI クライアントにサーバーを追加する

以下の設定ではローカル stdio を使用します。既存の設定項目はそのまま残し、etsy-mcp-server の項目だけを追加してください。HTTP URL を設定したり、Etsy のシークレットをこれらのファイルに記載したりしないでください。

Claude Desktop

Settings > Developer > Edit Config を開きます。標準の設定ファイルは、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json、Windows では %APPDATA%\Claude\claude_desktop_config.json です。Linux ではパスを決めつけず、Edit Config を使ってファイルを確認してください。公式のローカルサーバーガイドを参照してください。

macOS または Linux では、次を追加します。

{
	"mcpServers": {
		"etsy-mcp-server": {
			"command": "npx",
			"args": ["--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
		}
	}
}

Windows では、コマンドプロセッサーを使って npm コマンドの shim を起動します。

{
	"mcpServers": {
		"etsy-mcp-server": {
			"command": "cmd.exe",
			"args": ["/d", "/c", "npx.cmd", "--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
		}
	}
}

Claude Desktop を終了してから、再起動します。サーバーとそのツールが表示されることを確認してください。GitHub リポジトリのインポートや ZIP のインポートは、npm MCP のインストールではありません。このリポジトリでは、検証済みの .mcpb 拡張機能を現在配布していません。拡張機能の実現可能性に関するレビューを参照してください。

Claude Code

macOS または Linux の場合：

claude mcp add --transport stdio --scope user etsy-mcp-server -- npx --yes @profplum700/etsy-mcp-server@latest serve
claude mcp list

ネイティブ Windows の PowerShell の場合：

claude mcp add --transport stdio --scope user etsy-mcp-server -- cmd.exe /d /c npx.cmd --yes @profplum700/etsy-mcp-server@latest serve
claude mcp list

Claude Code 内で /mcp を使用して、接続を確認します。Claude Code のドキュメントでは、ユーザースコープと -- 区切り文字について説明しています。WSL で Claude Code を使用する場合は、WSL 内で Linux のセットアップ要件に従ってください。

OpenAI Codex

セットアップですでにサーバーが追加されている場合は、重複して追加しないでください。追加されていない場合は、macOS または Linux で次を実行します：

codex mcp add etsy-mcp-server -- npx --yes @profplum700/etsy-mcp-server@latest serve
codex mcp list

ネイティブ Windows の PowerShell の場合：

codex mcp add etsy-mcp-server -- cmd.exe /d /c npx.cmd --yes @profplum700/etsy-mcp-server@latest serve
codex mcp list

該当するローカル Codex クライアントを再起動し、CLI で /mcp を確認します。Codex MCP のドキュメントでは、config.toml を使った設定についても説明しています。このローカルコマンドでは、ホスト型クラウドタスクのアクセスは設定されません。

Cursor

お使いのオペレーティングシステムに対応する Claude Desktop の JSON ブロックを、個人用 Cursor 設定に追加します：

• macOS および Linux：~/.cursor/mcp.json。
• Windows：%USERPROFILE%\.cursor\mcp.json。

etsy-mcp-server オブジェクト内に "type": "stdio" を追加します。特定のプロジェクトだけで使用する場合は、そのプロジェクト内の .cursor/mcp.json を使用します。Cursor の MCP 設定を開き、etsy-mcp-server が有効で接続されていることを確認します。これらの場所と mcpServers の構造は、Cursor の MCP ドキュメントに従っています。

GitHub Copilot を使用する VS Code

現在の Copilot ハーネスセッションでは、チャット：カスタマイズを開く > MCP サーバー > サーバーを追加を開きます。**コマンド（stdio）**と、Copilot のグローバル保存先を選択します。お使いの OS に対応する Claude Desktop ブロックから、コマンドと引数の配列を入力します。個人用ファイルは $COPILOT_HOME/mcp-config.json です。未設定の場合は ~/.copilot/mcp-config.json になります。mcpServers を使用します。MCP サーバーを追加するを参照してください。

VS Code の設定形式を使用するには、MCP：ユーザー設定を開くを実行します。macOS または Linux では、次を追加します：

{
	"servers": {
		"etsy-mcp-server": {
			"type": "stdio",
			"command": "npx",
			"args": ["--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
		}
	}
}

Windows では、そのサーバーの command と args を次のように置き換えます：

{
	"command": "cmd.exe",
	"args": ["/d", "/c", "npx.cmd", "--yes", "@profplum700/etsy-mcp-server@latest", "serve"]
}

"type": "stdio" はそのままにします。ローカルのワークスペース設定には .vscode/mcp.json を使用します。servers ラッパーをポータブルな Copilot 形式にコピーしないでください。設定リファレンスでは、これらの形式の違いを説明しています。サーバーを再起動して出力を確認し、選択した Copilot セッションでツールを有効にします。リモートワークスペースには、独自のランタイムと認証情報ストアへのアクセスが必要です。

Gemini CLI

お使いのオペレーティングシステムに対応する Claude Desktop の JSON ブロックを、ユーザー設定に統合します：

• macOS および Linux：~/.gemini/settings.json。
• Windows：%USERPROFILE%\.gemini\settings.json。

既存の設定はそのまま残し、mcpServers と併存させます。Gemini CLI を再起動し、/mcp を実行して接続を確認します。ツールの確認を有効にしたままにしてください。Gemini CLI MCP ガイドでは、この形式と、オプションの gemini mcp add 登録コマンドについて説明しています。

接続を確認する

クライアントに etsy_get_my_shop を呼び出して、返されたショップ ID と名前を表示するよう依頼します。それらが意図したショップと一致することを確認します。次に、etsy_list_active_listings と limit: 1 を使って、アクティブなリスティングを 1 件取得するよう依頼します。サーバーの設定や起動成功だけでは、Etsy へのアクセスが確認されたことにはなりません。

サーバーは stdin と stdout を介して通信します。診断情報は stderr に出力されます。手動の serve コマンドは MCP クライアントを待ち受けるものであり、対話型シェルではありません。

各サーバープロセスは、起動時にアクティブなショップに紐付きます。アクティブなショップを変更しても、実行中の AI セッションが別のショップに切り替わることはありません。ショップを変更した後は、そのクライアントの MCP サーバーを再起動してください。ツールの実行が成功すると、照会したショップが結果に示されます。

ローカルの問題を診断する

クライアントと同じ環境のターミナルで診断を実行します。

npx --yes @profplum700/etsy-mcp-server@latest doctor
npx --yes @profplum700/etsy-mcp-server@latest doctor --json

Windows では、npx の代わりに npx.cmd を使用します。診断では、Etsy へのリクエストや保存済み認証情報の変更を行わずに、ローカルの前提条件と保存済み接続の準備状況を確認します。ネットワークアクセス、OAuth の更新、クライアント登録、または実際の API 権限を確認することはできません。JSON レポートには、schema_version、ok、および code、status、message を含む checks 配列が含まれます。ステータスは pass、warn、または fail です。失敗した場合は終了コード 1 が返されます。警告のみの場合は終了コード 0 が返されます。ショップ名、ID、ローカルパス、認証情報の値は出力されません。報告された対処法に従ってください。未リリースのソースチェックアウトで新しい診断をテストするには、ローカルでビルドして実行する必要があります。

症状	対処法
クライアントの出力に node または npx がない	Node.js 24 以降をインストールし、クライアントを再起動して PATH を継承させてください。
PowerShell で npx.ps1 の実行が拒否される	ターミナルで npx.cmd を使用してください。クライアントでは上記の Windows 用設定を使用してください。
Linux の Secret Service を利用できない	デスクトップのキーリングを起動してロックを解除してください。同じ D-Bus セッションでクライアントを実行してください。
macOS で Keychain へのアクセスが拒否される	ログイン Keychain のロックを解除し、Node プロセスに対する OS のアクセス許可プロンプトを確認してください。
保存済み接続がない、またはスコープが拒否された	対話型ターミナルでセットアップを実行し、shops_r と listings_r のみを許可してください。
セットアップでコールバックポートをバインドできない	ポート 3030 を使用しているプロセスを終了してから、セットアップを再実行してください。コールバックを未登録のアドレスに変更しないでください。
ターミナルでは動作するが、グラフィカルクライアントでコマンドが見つからない	macOS または Linux では command -v npx、Windows では where.exe npx.cmd を使って実行ファイルのパスを確認してください。その絶対パスをクライアントで使用してください。Windows のパスにスペースが含まれる場合は、下記の Node からの直接起動をおすすめします。
サーバーは接続するが、以前のショップが返される	使用するプロファイルを選択し、そのクライアントで MCP サーバーを再起動してください。

npm の起動時ダウンロードと Windows のコマンドシムの引用符処理を避けるには、確認済みのバージョンを npm install --global @profplum700/etsy-mcp-server@latest でグローバルにインストールしてください。npm root --global でパッケージディレクトリを、node -p "process.execPath" で Node の場所を確認します。絶対パスの Node 実行ファイルを command に設定し、絶対パスの <npm-root>/@profplum700/etsy-mcp-server/dist/cli.js と serve をそれぞれ別の args として指定してください。Windows では、パスをバックスラッシュをエスケープした JSON 文字列にしてください。この代替方法でも、同じ OS 認証情報ストアが必要です。

ショッププロファイルを管理する

セットアップを再実行して、別のショップを接続します。セットアップが成功するたびに、そのショップが追加または更新され、他のショップを置き換えることなくアクティブになります。

npx --yes @profplum700/etsy-mcp-server@latest status
npx --yes @profplum700/etsy-mcp-server@latest use "Test Shop"
npx --yes @profplum700/etsy-mcp-server@latest setup --reuse-app --manual-browser

最後のコマンドでは、保存済みの開発者アプリ認証情報が再利用されます。対象の Etsy アカウントにサインインしているブラウザプロファイルで、認証 URL を開いてください。

npx --yes @profplum700/etsy-mcp-server@latest disconnect
npx --yes @profplum700/etsy-mcp-server@latest disconnect --shop "Test Shop"
npx --yes @profplum700/etsy-mcp-server@latest disconnect --all
npx --yes @profplum700/etsy-mcp-server@latest remove-codex

Windows では npx.cmd を使用します。切断時には、認証情報を消去する前に確認が求められます。オプションを指定しない場合は、アクティブなショップが対象です。--shop は保存済みショップを 1 つ指定し、--all はすべてのショップを消去します。Codex の設定を削除しても、保存済みの Etsy 接続はそのまま残ります。

利用可能なツール

• etsy_get_my_shop は、接続されているショップの名前、ID、通貨、有効な出品数、URL を読み取ります。
• etsy_list_active_listings は、有効な出品のタイトル、基本価格、通貨、URL、状態を返します。1 ページあたり 1～50 件の出品をリクエストでき、オフセットは最大 10,000 まで指定できます。
• etsy_get_listing は、コンテンツのレビュー用に、接続されているショップの出品のタイトル、説明、タグ、素材、言語、状態、基本価格、URL を読み取ります。別のショップが所有する出品は拒否されます。
• etsy_get_listing_inventory は、接続されているショップが所有する出品のバリエーションの選択肢、価格、数量を返します。next_offset が null になるまでページを取得してください。各ページには提供内容ごとに 1 件が含まれるため、同じ商品が複数回表示されることがあります。

価格帯をレビューするには、有効な出品をページごとに取得し、基本価格で絞り込んでください。バリエーションの価格には在庫情報を使用します。これらのツールでは、配送対象かどうか、利益、注文売上、コンバージョン率は判断できません。すべてのツールは読み取り専用で、shops_r と listings_r 以外のスコープを要求しません。

クライアントの手順は、リンク先の公式ドキュメントに照らして 2026-10-24 に確認済みです。これらはサポート対象の設定形式を説明するもので、すべてのクライアントと OS の組み合わせで実行確認済みであることを示すものではありません。実行されたプラットフォームテストについては、実装レポートと CI の結果を参照してください。