Yahoo! Shopping MCP

Yahoo! Shopping MCP

Yahoo! Shopping Item Search API v3 を通じて、読み取り専用の商品検索を行う、オープンソースのコミュニティ保守型 MCP サーバーです。キーワードまたは JAN コードで検索でき、価格、在庫、商品の状態、送料、並べ替え、カテゴリ、ブランド、販売者、画像サイズ、ページネーションの各フィルターに対応しています。ローカル環境およびセルフホスト可能なデプロイでは Streamable HTTP を使用し、Glama のマネージドホスティングおよびローカルの stdio クライアント向けに、別途 stdio エントリーポイントを用意しています。

これは、Yahoo! Shopping、LINE Yahoo、OpenAI の公式サービスではありません。メンテナーは Yahoo! Shopping、Yahoo! Developer Network、OpenAI を代表しておらず、これらを推奨、運営、保証するものでもありません。

プロジェクトの状況とホスト型エンドポイント

このプロジェクトはセルフホストを想定しています。共有エンドポイントや本番環境向けのホスト型エンドポイントを保証して提供するものではありません。

メンテナーがテスト用に Cloudflare Tunnel の URL を別途共有する場合、その URL は一時的な検証用エンドポイントです。いつでも停止、再起動、変更される可能性があり、利用できなくなる場合もあります。稼働時間、SLA、サポート、プライバシー、データ保持に関する保証はありません。本番環境や機密性の高いワークロードには使用しないでください。代わりに、ご自身が管理するインフラストラクチャでこのサーバーを実行してください。

メンテナーが運用するサンプルデプロイを利用できる場合があります。

• MCP エンドポイント：https://non-official-yahoo-shopping-mcp.notelligent.app/mcp
• ヘルスチェック：https://non-official-yahoo-shopping-mcp.notelligent.app/healthz
• ルートのヘルスチェック：https://non-official-yahoo-shopping-mcp.notelligent.app/

これらの URL は、デモおよび接続確認のみを目的として提供されています。Yahoo! または OpenAI の公式サービスではなく、オンラインでの稼働、安定性、サポート、プライバシー、または特定のユーザーが利用できることは保証されません。

現在のレジストリおよびディレクトリへの掲載状況は、docs/PUBLICATION.md で確認できます。

これはコミュニティによる実装です。使用する前に、最新の Yahoo! Developer Network および Yahoo! Shopping API の利用規約、クォータ、帰属表示の要件、コンテンツ制限、およびお客様の管轄区域やデプロイに適用されるルールを、ご自身で確認してください。メンテナーは、この実装またはその使用が第三者のポリシーに準拠していることを保証しません。

デモ

以下の短いデモでは、ChatGPT から Yahoo! Shopping を検索し、MCP Apps の商品カルーセルが表示される様子を紹介します。

GitHub はリポジトリ内の MP4 ファイルをレンダリング済み Markdown に安定して埋め込めないため、インライン再生には GIF を使用しています。高画質の MP4 は assets/demo.mp4 で確認できます。

機能

• Yahoo! Shopping の商品検索を行う読み取り専用の search_products ツール
• キーワード、JAN コード、価格、在庫、商品の状態、送料、並べ替え、カテゴリ、ブランド、販売者、画像サイズ、ページネーションの各フィルター
• 同一プロセス内での Yahoo へのリクエスト開始間隔（デフォルトは 1 秒）
• Yahoo の HTTP 429 レスポンスに対する指数バックオフと、回数を制限した 5xx リトライ
• 安全性フィルターを適用した Yahoo レスポンスデータの短時間キャッシュ
• SQLite を使用したアプリケーション全体のレート制限
• Yahoo の帰属表示を含む MCP Apps の商品カルーセル
• 制限対象の商品用語および Yahoo 以外の URL の保守的なフィルタリング
• GET /、GET /healthz、および /mcp での Streamable HTTP MCP

レート制限はアプリケーション上の安全対策であり、Yahoo のクォータや SLA を保証するものではありません。1 つのプロセス内に適用されます。レプリカを分けて運用する場合は、個別の制御が必要です。

プロトコルとエンドポイント

デフォルトの yahoo-shopping-mcp エントリーポイントでは、MCP Streamable HTTP トランスポートを使用します。

• MCP エンドポイント：/mcp
• ヘルスエンドポイント：GET /healthz
• ルートヘルスエンドポイント：GET /
• MCP 認証：なし

サーバーはデフォルトでループバックにバインドされます。認証のないエンドポイントが 自動的にインターネットに公開されるわけではありません。公開する場合は、デプロイ環境に適した ネットワーク、リバースプロキシ、レート制限、ログ記録、データ保持の制御を追加してください。

Glama のマネージドホスティング

Glama のマネージド OSS ビルドは、stdio 経由で MCP プロセスを起動し、 Glama の HTTP ゲートウェイ経由でマネージドエンドポイントを公開します。Glama の Dockerfile 管理ページで、以下の CMD 引数を設定してください。

["uv", "run", "yahoo-shopping-mcp-stdio"]

Glama はこのコマンドを mcp-proxy ラッパーで囲みます。そのため、実際のマネージド コマンドは次と同等になります。

mcp-proxy -- uv run yahoo-shopping-mcp-stdio

このリポジトリの通常の yahoo-shopping-mcp コマンドと Dockerfile は、セルフホスト可能な Streamable HTTP のままです。Glama の環境スキーマで YAHOO_SHOPPING_APP_ID を設定し、 ビルドチェックには本番環境で使用しないプレースホルダーを指定してください。

ローカルプラグインパッケージ

このリポジトリには、ローカルでの使用向けのメタデータが含まれています。

• .codex-plugin/plugin.json：ローカルプラグインのメタデータ、プロンプト、ロゴ
• .mcp.json：ローカル MCP クライアントの設定
• assets/logo.svg：商品検索アイコン

これらのファイルは、ストアへの掲載や共有ホスティングサービスを提供するものではありません。 使用する前に、ご自身のサーバーを起動し、ご自身の Yahoo Client ID を設定してください。

クイックスタート

要件：Python 3.12 以降、uv、および運用者が取得した Yahoo! Shopping API の appid。

make sync-dev
YAHOO_SHOPPING_APP_ID="your-app-id" make run

ローカル MCP エンドポイントは http://127.0.0.1:8000/mcp、ヘルスチェックは http://127.0.0.1:8000/healthz です。

管理されたデプロイ環境で別のインターフェースまたはポートにバインドするには、次を実行します。

YAHOO_SHOPPING_APP_ID="your-app-id" make run HOST=0.0.0.0 PORT=8080

Yahoo Client ID は環境変数に保管してください。コミットしたり、検索クエリに含めたりしないでください。

Docker とセルフホスティング

ローカル環境用のテンプレートを作成し、コンテナーを起動します。

make init-env
make up

デフォルトのローカル Compose エンドポイントは http://127.0.0.1:18000/mcp です。本番環境向けのコンテナーおよびリバースプロキシの チェックリストについては、デプロイを参照してください。

Compose を使わずにコンテナーを直接実行するには、イメージをビルドし、コンテナーの ポートをループバックに公開します。

docker build --tag yahoo-shopping-mcp:local .
docker run --rm \
  --name yahoo-shopping-mcp \
  --publish 127.0.0.1:18000:8000 \
  --env YAHOO_SHOPPING_APP_ID="your-app-id" \
  --volume yahoo-shopping-mcp-data:/data \
  yahoo-shopping-mcp:local

MCP エンドポイントは http://127.0.0.1:18000/mcp、ヘルスチェックは http://127.0.0.1:18000/healthz です。公開済みのバージョン付きプレビューイメージを 使用するには、ローカルビルドを GitHub Container Registryの 特定のタグに置き換えます。

CONTAINER_IMAGE="ghcr.io/ymuichiro/yahoo-shopping-mcp:v0.9.0-preview.2"
docker pull "$CONTAINER_IMAGE"
docker run --rm \
  --name yahoo-shopping-mcp \
  --publish 127.0.0.1:18000:8000 \
  --env YAHOO_SHOPPING_APP_ID="your-app-id" \
  --volume yahoo-shopping-mcp-data:/data \
  "$CONTAINER_IMAGE"

アプリケーションを直接起動する場合は、YAHOO_SHOPPING_MCP_* 環境変数を使用してください。 Compose は、利便性のための変数 ALLOWED_HOSTS と ALLOWED_ORIGINS をアプリケーションの設定にマッピングします。

オプションの Cloudflare Tunnel

Cloudflare Tunnel は任意の開発者向けデプロイ方法であり、必須ではありません。 次の場合にのみ有効になります。

make up-tunnel

この Compose プロファイルを使用する場合に限り、CLOUDFLARE_TUNNEL_TOKEN を設定してください。 トンネルのホスト名と公開するアプリケーションは、このリポジトリ外の Cloudflare で設定します。 .env 内のローカル値を、デプロイで使用する正確な外部ホスト名とオリジンに置き換えてください。

YAHOO_SHOPPING_APP_ID=replace-with-your-yahoo-app-id
CLOUDFLARE_TUNNEL_TOKEN=replace-with-your-cloudflare-tunnel-token
ALLOWED_HOSTS=mcp.example.com
ALLOWED_ORIGINS=https://mcp.example.com

トンネルを使用しても、MCP 認証は追加されません。メンテナーが共有したトンネル URL を、 サポート対象のホスティングサービスとして扱わないでください。ご自身で管理するホスト名と インフラストラクチャを使用してください。

Claude Desktop

このリポジトリには、2 つの起動コマンドがあります。

• yahoo-shopping-mcp：ローカルまたはセルフホスト可能なデプロイ向けの Streamable HTTP
• yahoo-shopping-mcp-stdio：ローカルの stdio クライアントおよび Glama のマネージドホスティング向けの stdio

stdio エントリーポイントをローカルで実行するには、make sync-dev の実行後に 次の内容を claude_desktop_config.json に追加します。ディレクトリは、 このリポジトリへの絶対パスに置き換えてください。

{
  "mcpServers": {
    "yahoo-shopping": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/yahoo-shopping-mcp",
        "yahoo-shopping-mcp-stdio"
      ],
      "env": {
        "YAHOO_SHOPPING_APP_ID": "your-app-id"
      }
    }
  }
}

Yahoo Client ID はサーバー環境に保持し、決してコミットしないでください。

セルフホストされた認証済みデプロイに接続するには、Claude Desktop の Settings → Connectors → Add custom connector を開き、/mcp を含む完全な HTTPS MCP URL を入力します。

https://mcp.example.com/mcp

そのデプロイが提供する認証フローを完了してください。現在のメンテナー用デモ エンドポイントは認証されておらず、一時的なものです。そのため、本番環境の Claude コネクターとして使用しないでください。YAHOO_SHOPPING_APP_ID は MCP サーバーに 保持し、Claude Desktop の設定には決して記載しないでください。

ローカル開発では、サーバーを起動し、MCP Inspector でエンドポイントを確認してください。

YAHOO_SHOPPING_APP_ID="your-app-id" make run

Streamable HTTP エンドポイントは http://127.0.0.1:8000/mcp です。MCP ドキュメントのローカル サーバーおよびリモート サーバーを参照してください。

ツールの使用

ChatGPT Developer Mode または別の MCP クライアントから、起動したエンドポイントを 使用します。MCP 認証ヘッダーは必要ありません。

search_products では、query と jan_code の少なくとも一方が必要です。主な 制約は次のとおりです。

• query：1～200 文字
• jan_code：8～13 桁の数字の文字列
• genre_category_ids および brand_ids：1～20 個の正の整数からなる配列
• results：1～50
• start：1 以上
• start + results <= 1000
• 両方が指定されている場合は、price_from <= price_to

完全な仕様については、docs/API.md を参照してください。

例：

{
  "query": "desk lamp",
  "in_stock": true,
  "sort": "-score",
  "results": 10,
  "start": 1
}

このツールは、モデルが読み取り可能な JSON を content[0].text に返し、商品データを results に含めます。カルーセルデータは structuredContent.products に返されます。 UI リソースのバージョンは ui://yahoo-shopping/product-carousel-v4.html で、Yahoo のクレジットを表示します。

このサーバーは、注文の受付、支払いの処理、アカウントの変更を行わず、商品の在庫状況、 価格、販売者、配送、法令遵守も保証しません。

プライバシーと安全性

検索フィールドは、運営者の MCP サーバーと Yahoo! Shopping に送信されます。 サーバーは、安全性フィルターを適用した Yahoo の応答データのみを短期間のキャッシュに、 全体のレート制限状態をローカルストレージに保存します。ユーザーアカウントの提供や、 チャット履歴全体の永続化は行いません。

検索語として、秘密情報、支払い情報、パスワード、政府発行の識別情報、機微な個人情報を 送信しないでください。公開運営者は、実際のインフラストラクチャに即したプライバシー、 サポート、データ保持に関する詳細を公開する必要があります。

安全性フィルターは保守的な設定であり、商品の分類を完全に保証するものではありません。 Yahoo のポリシー、法律上の助言、または運営者による確認に代わるものではありません。

PRIVACY.md、TERMS.md、 SECURITY.md、および docs/DATA_HANDLING.md を参照してください。

Yahoo! Developer Network references

The following official pages define the external requirements that apply to the operator's own Yahoo! application. They are not part of this repository's license or a substitute for reading the current versions:

• Yahoo! Developer Network guidelines
• Yahoo! Shopping API portal
• Yahoo! Shopping product search v3
• Credit and attribution rules
• Usage limits
• Developer guide and Client ID registration

Each operator must obtain and protect their own Client ID and independently confirm the applicable terms, usage limits, attribution, and legal requirements before operating this server.

Development and verification

make test

Tests use httpx.MockTransport and do not call Yahoo! from CI. For MCP Inspector and UI checks, see docs/VERIFICATION.md. Reviewable positive and negative cases are in docs/SUBMISSION_TEST_CASES.md.

Contributions are welcome. Read CONTRIBUTING.md before opening a change. For support, use SUPPORT.md; report security issues using the private process in SECURITY.md.

Japanese documentation

日本語の概要・導入手順は docs/README.ja.md を参照してください。

License

MIT