内容
# rakuten-mcp-search
楽天市場の商品を検索し、**サイズ・カラー別の在庫状況**を確認できるMCPサーバーと検索UIです。
楽天の商品ページでは複数のサイズ・カラーが1ページにまとめられていますが、一覧画面ではバリアントごとの在庫が確認できません。このツールを使うと、「17cmのネイビーは在庫あり？」といった問いに自然言語で答えられます。
---
## ファイル構成
```
rakuten-mcp-search/
├── src/rakuten_mcp/
│ ├── server.py # MCPサーバー (3ツール)
│ ├── api_client.py # 楽天APIクライアント
│ ├── scraper.py # 商品ページ バリアント解析
│ └── web_server.py # 検索UI用 Webサーバー
├── web/
│ └── index.html # 検索UI（画像・バリアント在庫表示）
├── pyproject.toml
└── .env.example
```
---
## セットアップ
### 1. APIキーの取得
楽天ウェブサービスのAPIキーが必要です。
1. [楽天ウェブサービス](https://webservice.rakuten.co.jp/) にアクセスし、楽天IDでログイン
2. 「アプリ登録」→「新規アプリを作成」をクリック
3. アプリ名・アプリURL・使用サービスを入力して登録
- 許可されたWebサイト: 公開予定がない（ローカルのみ）の場合でも何かしらのドメインを入れておく（例: test-app.local）
4. 発行された **アプリID（`applicationId`）** と **アクセスキー（`accessKey`）** を控える
> APIキーは1アカウントにつき最大5アプリまで登録できます。
> 登録URL: https://webservice.rakuten.co.jp/app/create
**「許可されたウェブサイト」の設定**
アプリ登録時に設定した「許可されたウェブサイト」のURLを `.env` の `RAKUTEN_APP_URL` に**完全一致**で設定してください。
不一致だと API 呼び出し時に `REQUEST_CONTEXT_BODY_HTTP_REFERRER_MISSING` (403) エラーになります。
### 2. インストール
```bash
git clone https://github.com/yourname/rakuten-mcp-search
cd rakuten-mcp-search
uv venv
uv pip install -e .
```
### 3. 環境変数の設定
```bash
cp .env.example .env
```
`.env` を編集して取得したAPIキーを設定します:
```
RAKUTEN_APP_ID=your_application_id_here
RAKUTEN_ACCESS_KEY=your_access_key_here
RAKUTEN_APP_URL=https://your-registered-app-url.example.com
PORT=8765
```
---
## 使い方
### 検索UI（ブラウザ）
```bash
source .venv/bin/activate
rakuten-web
```
`.env` に設定したAPIキーが自動で読み込まれます。
ブラウザで http://localhost:8765 を開きます。
- 検索ボックスにキーワードを入力して商品一覧・画像を表示
- 「在庫確認」ボタンで各商品のサイズ・カラー別在庫をその場で確認
- 「在庫で絞り込み」でサイズ・カラーを指定すると、該当バリアントが在庫ありの商品だけを検索・表示
### MCPサーバー（Claude Desktop連携）
MCPサーバーは**Claude Desktopなどのクライアントが自動的に起動・管理**します。手動で `rakuten-mcp` を実行しておく必要はありません。
これはMCPがstdioモードで動作しているためで、Claude Desktopが設定に従って `wsl.exe` 経由で `rakuten-mcp` プロセスを自動的に起動・終了します。`rakuten-web`（ブラウザUI用サーバー）を別途起動しておく必要もありません。
`claude_desktop_config.json` に設定を追加するだけで動作します。
**APIキーの設定は `.env` ファイルのみで完結します。**
サーバー起動時にプロジェクトルートの `.env` が自動的に読み込まれるため、MCP設定ファイルに `env` 欄を追加する必要はありません。
---
## Claude Desktop 設定
### Mac / Linux（ネイティブ環境）
`~/.claude/claude_desktop_config.json` または `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"rakuten": {
"command": "/path/to/rakuten-mcp-search/.venv/bin/rakuten-mcp"
}
}
}
```
または `uv` を使う場合:
```json
{
"mcpServers": {
"rakuten": {
"command": "uv",
"args": ["run", "--directory", "/path/to/rakuten-mcp-search", "rakuten-mcp"]
}
}
}
```
### Windows Claude Desktop + WSL
`%APPDATA%\Claude\claude_desktop_config.json`:
```json
{
"mcpServers": {
"rakuten": {
"command": "wsl.exe",
"args": [
"--exec",
"/home/<username>/.local/bin/uv",
"run",
"--directory",
"/home/<username>/repos/rakuten-mcp-search",
"rakuten-mcp"
]
}
}
}
```
`<username>` はWSLのユーザー名に置き換えてください。
`uv` のパスは `which uv`（WSL内）で確認できます。
> `.env` はWSL内のプロジェクトルートに置けば起動時に自動読み込みされます。
> Windows側のMCP設定ファイルに `env` 欄を追加する必要はありません。
---
## MCPツール一覧
| ツール | 説明 |
|--------|------|
| `rakuten_search` | キーワードで商品を検索し、一覧（名前・価格・ショップ・レビュー）を返す |
| `rakuten_get_item_variants` | 商品URLを指定してサイズ・カラー別の在庫状況を取得 |
| `rakuten_search_with_stock` | 検索＋指定バリアントの在庫確認を一括実行 |
### 使用例（Claude）
```
子供用スニーカーで17cmのネイビーが在庫ある商品を探して
```
```
https://item.rakuten.co.jp/xxx/yyy/ のサイズ別在庫を教えて
```
```
キッズサンダルを検索して、18cmのピンクがある商品だけ教えて。予算は3000円以内で
```
---
## 仕組み
1. **楽天商品検索API** でキーワードに一致する商品一覧を取得
2. 各商品ページをスクレイピングして埋め込みJSONオブジェクト `itemInfoSku` を解析
3. `variantSelectors`（サイズ・カラー軸）と `variantMappedInventories`（在庫数）を組み合わせてバリアント別在庫を表示
> **注意**: 楽天の公開APIはバリアントレベルの在庫情報を提供していないため、商品ページのスクレイピングを利用しています。楽天の利用規約に従い、個人利用の範囲でご使用ください。
---
## 動作要件
- Python 3.10 以上
- 楽天ウェブサービス APIキー（無料）
