Content
# Tool List
Rakuten Market product search and size/color stock status confirmation tool with MCP server and search UI.
Rakuten's product pages list multiple sizes and colors on a single page, but the list view does not show inventory for each variant. This tool allows you to answer questions like "Is there stock for 17cm navy blue?" in natural language.
## File Structure
```
rakuten-mcp-search/
├── src/rakuten_mcp/
│ ├── server.py # MCP Server (3 tools)
│ ├── api_client.py # Rakuten API Client
│ ├── scraper.py # Product page variant analysis
│ └── web_server.py # Search UI Web Server
├── web/
│ └── index.html # Search UI (image and variant stock display)
├── pyproject.toml
└── .env.example
```
## Setup
### 1. Obtain API Key
Rakuten Web Service API key is required.
1. Access [Rakuten Web Service](https://webservice.rakuten.co.jp/) and log in with Rakuten ID
2. Click "App Registration" -> "Create New App"
3. Enter app name, app URL, and services used, then register
- Allowed Web Sites: Enter a domain even if there are no plans to make it public (e.g., test-app.local)
4. Note down the issued **App ID (`applicationId`)** and **Access Key (`accessKey`)**
> API keys can be registered for up to 5 apps per account.
> Registration URL: https://webservice.rakuten.co.jp/app/create
**Allowed Website Setting**
Set the "Allowed Website" URL configured during app registration to `.env`'s `RAKUTEN_APP_URL` with **exact match**. Mismatch will result in `REQUEST_CONTEXT_BODY_HTTP_REFERRER_MISSING` (403) error during API calls.
### 2. Installation
```bash
git clone https://github.com/yourname/rakuten-mcp-search
cd rakuten-mcp-search
uv venv
uv pip install -e .
```
### 3. Environment Variable Setup
```bash
cp .env.example .env
```
Edit `.env` to set the obtained API keys:
```
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
```
## Usage
### Search UI (Browser)
```bash
source .venv/bin/activate
rakuten-web
```
The API keys set in `.env` are automatically loaded.
Open http://localhost:8765 in the browser.
- Enter keywords in the search box to display product list and images
- Click "Check Stock" button to confirm stock for each product's size and color
- Use "Filter by Stock" to search and display products with specific size and color variants in stock
### MCP Server (Claude Desktop Integration)
The MCP server is **automatically launched and managed by clients like Claude Desktop**. There is no need to manually run `rakuten-mcp`.
This is because MCP operates in stdio mode, and Claude Desktop automatically launches and terminates the `rakuten-mcp` process via `wsl.exe` according to the settings. There is also no need to launch `rakuten-web` (browser UI server) separately.
Add settings to `claude_desktop_config.json` to enable functionality.
**API key settings are only required in the `.env` file.**
The `.env` file in the project root is automatically loaded when the server starts, so there is no need to add an `env` section to the MCP settings file.
## Claude Desktop Configuration
### Mac / Linux (Native Environment)
`~/.claude/claude_desktop_config.json` or `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"rakuten": {
"command": "/path/to/rakuten-mcp-search/.venv/bin/rakuten-mcp"
}
}
}
```
Or using `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"
]
}
}
}
```
Replace `<username>` with your WSL username.
Verify the path to `uv` using `which uv` (in WSL).
> Place `.env` in the project root in WSL for automatic loading during startup.
> No need to add an `env` section to the MCP settings file on Windows.
## Tool List
| Tool | Description |
|--------|------|
| `rakuten_search` | Search products by keyword and return list (name, price, shop, review) |
| `rakuten_get_item_variants` | Get stock status for size and color variants by product URL |
| `rakuten_search_with_stock` | Perform search and stock confirmation for specified variants in one go |
### Example Usage (Claude)
```
Find kids' sneakers with 17cm navy blue in stock
```
```
Tell me the stock status for size variants of https://item.rakuten.co.jp/xxx/yyy/
```
```
Search for kids' sandals with 18cm pink in stock, budget within 3000 yen
```
## Mechanism
1. **Rakuten Product Search API** retrieves product list matching keywords
2. Scrapes each product page to analyze embedded JSON object `itemInfoSku`
3. Combines `variantSelectors` (size and color axes) and `variantMappedInventories` (stock quantity) to display variant stock
> **Note**: Rakuten's public API does not provide variant-level stock information, so product page scraping is used. Use within personal usage limits according to Rakuten's terms of service.
## System Requirements
- Python 3.10 or higher
- Rakuten Web Service API key (free)
