Etsy MCP Server

Etsy MCP サーバー

Etsy API と連携するための MCP（Model Context Protocol）サーバーです。このサービスは、認証、出品情報の管理、ショップの詳細情報や配送プロファイルの取得、画像のアップロードに関する Etsy API 呼び出しを処理します。

概要

このサービスは、Model Context Protocol（MCP）経由で利用できる一連のツールを提供し、Etsy V3 API と連携します。OAuth 2.0 認証フロー（PKCE トークンの更新を含む）を管理し、トークンを安全に保存するとともに、出品情報の作成、ショップデータの取得、配送プロファイルの管理、画像のアップロードなどの機能を提供します。MCP 対応クライアントが Etsy API を簡単に利用できるようにすることを目的としています。

この MCP サーバーは、主に開発およびツール連携を目的として設計されています。Etsy の API 利用規約を遵守してください。

機能

• 🔑 OAuth2 認証：PKCE を使った Etsy OAuth2 フロー全体を処理します。
• 🛍️ 出品情報の管理：Etsy の出品情報を作成、取得します。
• ℹ️ ショップ情報：Etsy ショップの詳細情報を取得します。
• 📦 配送プロファイル：ショップの配送プロファイルを一覧表示、作成します。
• 🖼️ 画像のアップロード：画像をアップロードし、出品情報に関連付けます。
• 🔧 デフォルトショップの管理：複数のショップを簡単に利用できるよう、デフォルトのショップを設定、取得します。
• 🔒 トークンの安全な保存：OAuth トークンを安全に保持します。

インストール

前提条件

• Node.js（package.json の engines を参照。バージョン 18.0.0 以上を推奨）
• npm（通常は Node.js に付属）または yarn

手動インストール

1. リポジトリをクローンします（GitHub／GitLab などでホストしている場合は、リポジトリ URL に置き換えてください）：

   git clone <your-repository-url>
   cd etsy-mcp
   

   （ローカルで作業している場合は、クローンせずにプロジェクトディレクトリへ cd するだけでかまいません。）

2. 依存関係をインストールします：

   npm install
   

   yarn を使用する場合：

   yarn install
   

3. 環境変数を設定します： .env.example ファイルを .env という名前の新しいファイルにコピーします：

   cp .env.example .env
   

   次に、.env を開き、Etsy アプリの認証情報を入力します：

   ETSY_API_KEY=YOUR_ETSY_APP_API_KEY
   ETSY_CLIENT_SECRET=YOUR_ETSY_APP_CLIENT_SECRET
   # Optional: define a specific host and port for the OAuth callback redirect URI
   # ETSY_MCP_HOST=localhost
   # ETSY_MCP_OAUTH_PORT=3003
   # ETSY_MCP_REDIRECT_URI=http://localhost:3003/oauth/callback
   # Optional: define a custom path for token storage and logs
   # ETSY_MCP_TOKEN_PATH=/path/to/your/token_storage_directory
   # ETSY_MCP_LOG_PATH=/path/to/your/logs_directory
   # Optional: Your default shipping profile ID for physical items
   # SHIPPING_PROFILE_ID=YOUR_DEFAULT_SHIPPING_PROFILE_ID
   

   注：.env ファイル内の REDIRECT_URI（またはデフォルトの http://localhost:3003/oauth/callback）は、Etsy アプリに設定したリダイレクト URI のいずれかと一致している必要があります。

使い方

サービスの実行

• 本番環境／ビルド済みバージョンの場合：

  npm run build
  npm start
  

• 自動再読み込みを有効にした開発の場合：

  npm run dev
  

これによりサーバーが起動し、通常は標準入出力経由で MCP コマンドを待ち受けます。

Cursor IDE（またはその他の MCP クライアント）での使用

この Etsy MCP サーバーを Cursor IDE などの MCP クライアントで使用するには、通常、JSON 設定を指定します。

Cursor の設定で MCP タブに移動し、「+ Add new global MCP server」をクリックして、次の内容を入力します。

{
    "mcpServers": {
        "Etsy MCP": {
            "command": "npm",
            "args": ["run", "dev"],
            "env": {
                "ETSY_API_KEY": "YOUR_ETSY_API_KEY_HERE",
                "ETSY_CLIENT_SECRET": "YOUR_ETSY_CLIENT_SECRET_HERE"
                // Add other ENV VARS from your .env if needed, e.g., REDIRECT_URI
                // "REDIRECT_URI": "http://localhost:3003/oauth/callback"
                // "SHIPPING_PROFILE_ID": "YOUR_DEFAULT_SHIPPING_PROFILE_ID_HERE"
            },
            "cwd": "/Users/name/Desktop/repos/ai gemini apps/etsy_api/etsy-mcp" // IMPORTANT: Update this to the correct absolute path of your project
        }
    }
}

クライアント設定の主なポイント：

• command & args：この例では、開発用に npm run dev を使用しています。本番環境では、npm start を使用できます（まだビルドされていない場合は、事前に npm run build が実行されます）。
• env：
  • npm run dev スクリプトの環境から .env ファイルが読み込まれることに頼りたくない場合は、YOUR_ETSY_API_KEY_HERE と YOUR_ETSY_CLIENT_SECRET_HERE を実際の認証情報に置き換えてください。通常は、サーバーに .env ファイルから認証情報を読み込ませるのが適切です。上記の例は、クライアントの実行環境で認証情報を上書きするか、確実に設定するためのものです。
• cwd：お使いのマシン上で etsy-mcp プロジェクトが配置されている絶対パスに必ず更新してください。
• tools 配列もここで定義できますが、サーバー自体が機能を報告するため、クライアントが機能を動的に取得できる場合は、クライアント側の静的設定で必ずしも指定する必要はありません。

API リファレンス

このサービスは、次の MCP ツールを提供します。パラメーターは、サーバーで定義された Zod スキーマに基づいています。

authenticate()

Etsy の OAuth2 認証フローを開始します。

• 説明：認証プロセスを開始します。サーバーから返される URL をブラウザーで開き、Etsy アカウントへのアクセスを許可する必要があります。
• パラメーター：なし。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "Please visit this URL to authorize the application: https://www.etsy.com/oauth/connect?response_type=code&client_id=YOUR_API_KEY...\nComplete the process in your browser. You can then use other tools."
    }
  ]
}

set_default_shop()

Etsy のショップを取得し、最初に見つかったショップをこのセッションのデフォルトに設定します。

• 説明：認証に成功した後、このツールを使用してデフォルトのショップを選択します。複数のショップがある場合、Etsy から返された最初のショップが自動的に使用されます。shop_id を明示的に指定しない限り、このデフォルトのショップが他のツールで使用されます。
• パラメーター：なし。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "Default shop set to: YourShopName (ID: 12345678). Other tools will now use this shop unless a specific shop_id is provided."
    }
  ]
}

ショップが見つからない場合：

{
  "content": [
    {
      "type": "text",
      "text": "No shops found for your Etsy account."
    }
  ]
}

get_default_shop()

現在設定されているデフォルトの Etsy ショップ ID と名前を取得します。

• 説明：現在どのショップがデフォルトに設定されているかを確認するには、このツールを使用します。
• パラメーター：なし。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "Current default shop: YourShopName (ID: 12345678)"
    }
  ]
}

デフォルトのショップが設定されていない場合：

{
  "content": [
    {
      "type": "text",
      "text": "No default shop is currently set. Please run the `set_default_shop` tool after authenticating."
    }
  ]
}

get_listings(shop_id?: number)

ショップの有効なリスティングをすべて取得します。

• パラメーター：
  • shop_id（number、任意）：ショップの ID。指定しない場合は、デフォルトのショップが使用されます。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"listing_id\": 123456789,\n      \"user_id\": 98765432,\n      \"shop_id\": 12345678,\n      \"title\": \"Handmade Ceramic Mug\",\n      \"description\": \"A beautiful handmade ceramic mug...\",\n      \"state\": \"active\",\n      \"price\": { \"amount\": 2500, \"divisor\": 100, \"currency_code\": \"USD\" },\n      \"quantity\": 5,\n      /* ... other listing fields ... */\n    }\n  ]\n}"
    }
  ]
}

get_shop_details(shop_id?: number)

特定のショップの詳細を取得します。

• パラメーター：
  • shop_id（number、任意）：ショップの ID。指定しない場合は、デフォルトのショップが使用されます。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"shop_id\": 12345678,\n  \"shop_name\": \"YourShopName\",\n  \"user_id\": 98765432,\n  \"title\": \"Unique Handmade Goods\",\n  \"status\": \"active\",\n  /* ... other shop fields ... */\n}"
    }
  ]
}

create_listing(shop_id?: number, listing_data: object)

新しい Etsy リスティングを作成します。

• 説明：物理商品の場合は、shipping_profile_id が設定されていることを確認してください。画像を追加するには、まずリスティングを作成し、返された listing_id を使って upload_listing_image ツールを使用します。
• パラメーター：
  • shop_id（number、任意）：ショップの ID。指定しない場合は、デフォルトのショップが使用されます。
  • listing_data（object）：
    • title（string）：リスティングのタイトル。
    • description（string）：リスティングの説明。
    • price（number）：リスティングの価格（例：25.99）。
    • quantity（number）：在庫数。
    • who_made（string）：例：'i_did'、'collective'、'someone_else'。
    • when_made（string）：例：'made_to_order'、'2020_2024'、'1950_1959'。
    • taxonomy_id（number）：リスティングのカテゴリーの数値 ID。
    • shipping_profile_id（number、任意）：配送プロファイルの数値 ID。type が 'physical' の場合は必須です。
    • type（enum："physical"、"digital"、"download"）：リスティングの種類。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"listing_id\": 123456790,\n  \"user_id\": 98765432,\n  \"shop_id\": 12345678,\n  \"title\": \"New Awesome Product\",\n  /* ... other fields of the newly created listing ... */\n}"
    }
  ]
}

list_shop_shipping_profiles(shop_id?: number)

指定したショップの配送プロファイルをすべて一覧表示します。

• パラメーター：
  • shop_id（number、任意）：ショップの ID です。指定しない場合は、デフォルトのショップを使用します。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"count\": 1,\n  \"results\": [\n    {\n      \"shipping_profile_id\": 7654321,\n      \"title\": \"Standard US Shipping\",\n      \"origin_country_iso\": \"US\",\n      /* ... other shipping profile fields ... */\n    }\n  ]\n}"
    }
  ]
}

create_shop_shipping_profile(shop_id?: number, title: string, origin_country_iso: string, primary_cost: number, secondary_cost: number, min_processing_time: number, max_processing_time: number, destination_country_iso?: string, destination_region?: string)

ショップの新しい配送プロファイルを作成します。

• パラメーター：
  • shop_id（number、任意）：ショップの ID です。指定しない場合は、デフォルトのショップを使用します。
  • title（string）：配送プロファイルのタイトルです（例：'US Standard'）。
  • origin_country_iso（string、長さ 2）：発送元の国の ISO コードです（例：'US'）。
  • primary_cost（number、最小値 0）：この配送先への単独配送の送料です。
  • secondary_cost（number、最小値 0）：別の商品と同梱する場合の送料です。
  • min_processing_time（integer、最小値 1）：注文処理にかかる最短日数です。
  • max_processing_time（integer、最小値 1）：注文処理にかかる最長日数です。
  • destination_country_iso（string、長さ 2、任意）：特定の配送先の国の ISO コードです。
  • destination_region（enum："eu"、"non_eu"、"none"、任意）：特定の配送先地域です。 (注：destination_country_iso と destination_region のどちらか一方を指定する必要があります。両方は指定できません。)
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"shipping_profile_id\": 7654322,\n  \"title\": \"New Express Profile\",\n  /* ... other fields of the newly created shipping profile ... */\n}"
    }
  ]
}

upload_listing_image(shop_id?: number, listing_id: number, file_name: string, image_name?: string)

定義済みのローカルサーバーディレクトリから画像をアップロードし、Etsy の出品に関連付けます。

• 説明：出品を作成した後、このツールを使用して画像をアップロードします。画像はサーバー上の public/uploads/listing_images ディレクトリ（プロジェクトルートからの相対パス）に配置してください。
• パラメーター：
  • shop_id（number、任意）：ショップ ID です。指定しない場合はデフォルトを使用します。
  • listing_id（integer）：画像を追加する出品の ID です。
  • file_name（string）：サーバーの public/uploads/listing_images ディレクトリにある画像ファイルの名前です（例：'my_image.jpg'）。
  • image_name（string、任意）：Etsy 上での画像のファイル名です。指定しない場合は file_name が使用されます。
• 戻り値：

{
  "content": [
    {
      "type": "text",
      "text": "{\n  \"listing_image_id\": 987654321,\n  \"listing_id\": 123456790,\n  \"hex_code\": \"f1e2d3\",\n  \"url_75x75\": \"https://.../75x75.jpg\",\n  /* ... other image details ... */\n}"
    }
  ]
}

動作の仕組み

1. クライアントからのリクエスト：MCP クライアントがこのサーバーにツール呼び出しリクエストを送信します（ローカルで実行する場合は、たとえば stdio を介して送信します）。
2. 認証チェック：認証が必要なツールの場合、サーバーは TokenStorage を使用して有効な OAuth トークンがあるか確認します。
3. OAuth フロー（必要な場合）： a. 有効なトークンが存在しない場合、通常、クライアントが authenticate ツールを呼び出します（またはサーバーから呼び出すよう指示されます）。 b. EtsyMCPServer が OAuthServer を呼び出し、Etsy の認証 URL を生成します（PKCE を使用）。 c. ユーザーがこの URL をブラウザーで開き、アプリケーションを承認します。 d. Etsy が認証コードを付けて OAuthServer のコールバックエンドポイントにリダイレクトします。 e. OAuthServer が PKCE コード検証子を使用してコードを交換し、アクセストークンとリフレッシュトークンを取得します。 f. user_id と、場合によってはデフォルトの shop_id および shop_name を含むトークンが、TokenStorage によって保存されます。
4. API 呼び出し：EtsyMCPServer は、アクセストークンを保持する EtsyApiClient を使用して、Etsy V3 API に要求された API 呼び出しを行います。
5. トークンの更新：アクセストークンの有効期限が切れている場合、EtsyMCPServer の getValidAccessToken() はリフレッシュトークンを使用して新しいアクセストークンを取得しようとします。
6. レスポンス：Etsy API からのレスポンスが処理され、標準の MCP 形式で MCP クライアントに返されます。

トラブルシューティング

• 認証エラー／無効なグラント：
  • .env 内の ETSY_API_KEY と ETSY_CLIENT_SECRET が正しいことを確認してください。
  • サーバーが使用する REDIRECT_URI（デフォルトは http://localhost:3003/oauth/callback、または .env で設定した値）が、Etsy アプリの設定で構成した「Callback URLs」のいずれかと完全に一致していることを確認してください。
  • トークンが古い場合：トークンの保存先（TokenStorage.ts または ETSY_MCP_TOKEN_PATH 環境変数を参照）から tokens.json を削除し、再認証してください。
• OAuth サーバーの EADDRINUSE：OAuth コールバックサーバー用のポート（デフォルトは 3003）がすでに使用されていることを意味します。別のプロセスを停止するか、.env ファイルの ETSY_MCP_OAUTH_PORT を別の値に設定し、それに応じて Etsy アプリのリダイレクト URI を更新してください。
• 画像アップロード時にファイルが見つからない：upload_listing_image に指定した file_name が、プロジェクトのルートディレクトリからの相対パスで public/uploads/listing_images/ ディレクトリ内に存在することを確認してください。
• ログファイル：詳細なエラーメッセージについては、logs ディレクトリ（または ETSY_MCP_LOG_PATH）に生成されたログファイルを確認してください。実行するたびに、タイムスタンプ付きのログファイルが作成されます。

ライセンス

MIT License（このライセンスを選択する場合は、MIT License のテキストを含む LICENSE ファイルを作成するか、別のライセンスを指定してください。）

スポンサー

• Resold
• Vinta
• House Illustrator
• GitClip