rakuten-japan-mcp

Rakuten Japan MCP — 乐天市场商品搜索与排行榜

通过乐天官方 API 搜索乐天市场商品并获取当前排行榜。
以简洁、结构化的 JSON 提取商品名称、价格、URL、店铺信息、评价和图片。

---

🚀 功能介绍

此 Actor 封装了乐天官方 API，并通过两种方式提供服务：

1. 传统的 Apify Actor — 可通过 Apify Console、API 运行，也可设置定时运行
2. MCP 服务 — 连接 AI Agent（Claude、Cursor、ChatGPT），实时查询乐天市场

两种数据访问模式：

• 商品搜索 — 官方 IchibaItem/Search API（关键词搜索）
• 排行榜 — 官方 IchibaItem/Ranking API（热门商品、分类排行榜、历史时期）

为什么使用它？ 乐天是日本最大的电商平台，拥有数百万件商品。此 Actor 可通过符合 TOS 的官方 API，以编程方式访问商品和排行榜数据，无需抓取 HTML 或管理代理。

---

🔧 用法

作为 Apify Actor

1. 商品搜索 — 设置 searchKeyword（例如「ポケモン」、「フィギュア」、「PS5」），并可选择设置筛选条件。

2. 排行榜 — 将 ranking 设为 true，也可通过 genreId 缩小范围：

参数	类型	默认值	说明
ranking	boolean	false	设为 true 时获取排行榜，而非搜索结果
genreId	integer	—	限定商品分类（例如 101269=图书・杂志，101347=玩具）
rankingType	select	item	item、male 或 female
era	string	—	历史排行榜时期 YYYYMMDD（例如 20190601）
maxResults	int	30	最大结果数（每次调用最多获取 30 条排行榜结果）

作为 MCP 服务

将任何兼容 MCP 的客户端连接到该 Actor 的待机端点。

工具：

• search_rakuten — 按关键词搜索商品，返回标题/价格/URL/店铺/评价/图片
• search_rakuten_ranking — 获取当前乐天排行榜（分类/男性/女性/历史时期）
• get_actor_info — 获取工具和定价列表

---

🧹 官方 API 详情

• 搜索： https://openapi.rakuten.co.jp/ichibams/api/IchibaItem/Search/20260701
• 排行榜： https://app.rakuten.co.jp/services/api/IchibaRanking/Ranking/20220601

搜索需要 RAKUTEN_APP_ID 和 RAKUTEN_ACCESS_KEY；排行榜只需要 RAKUTEN_APP_ID。这些是设置在 Apify Actor 上的 Secret 环境变量。

---

🧪 测试与类型检查

python -m pytest tests/ -v
python -m mypy src/ --strict

推送到 master/main 时，会通过 GitHub Actions 自动部署。

---

🔒 定价（按事件付费）

• rakuten-search：每次搜索 $0.001
• rakuten-ranking：每次排行榜查询 $0.001

MCP 注册表

此服务已在官方 MCP 注册表 中注册。 可通过搜索找到：rakuten-japan-mcp

---

数据与商店

• Apify Store： https://apify.com/fruitful_quintessence
• Gumroad 数据集： https://atushi5.gumroad.com/l/kutuxe