Rakuten Mcp

rakuten-mcp

适用于 Rakuten Web Service API 的 Model Context Protocol 服务。提供 27 个只读工具，涵盖乐天旗下六个产品系列：Ichiba（购物市场）、Books、Travel、Recipe、Kobo 和 GORA（高尔夫）。

每个工具的说明均提供英语和日语版本。所有端点均已于 2026-10-04 根据乐天实时 API 及其文档重新验证。

安装

npm install -g rakuten-mcp

也可以按需运行 npx rakuten-mcp。

配置

1. 在 Rakuten Web Service 注册。
2. 创建应用。你将获得一个 UUID 格式的 Application ID 和一个以 pk_ 开头的 Access Key。
3. 可选：注册 Affiliate ID，以通过商品链接获利。工具响应中的商品 URL 将包含该 ID。

变量	必填	描述
RAKUTEN_APP_ID	是	Application ID（新平台采用 UUID 格式）
RAKUTEN_ACCESS_KEY	是	Access Key（以 pk_ 开头）
RAKUTEN_AFFILIATE_ID	否	添加到每个商品 URL 的 Affiliate ID
RAKUTEN_MAX_RETRIES	否	遇到 429 / 5xx 时的重试次数。默认为 3。

IP 允许列表。 乐天应用可以限制可调用该应用的 IP 地址。如果你的 IP 地址发生变化（切换网络、重启路由器），所有工具都会失败并返回 CLIENT_IP_NOT_ALLOWED；服务会将其报告为 IP 问题，而非密钥问题。请在 webservice.rakuten.co.jp/app/list 中该应用的 Edit 页面进行修复。服务器和 CI 运行器的出口 IP 也需要加入列表。

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "rakuten": {
      "command": "npx",
      "args": ["-y", "rakuten-mcp"],
      "env": {
        "RAKUTEN_APP_ID": "your-app-id",
        "RAKUTEN_ACCESS_KEY": "your-access-key"
      }
    }
  }
}

Claude Code

claude mcp add rakuten -e RAKUTEN_APP_ID=... -e RAKUTEN_ACCESS_KEY=... -- npx -y rakuten-mcp

Cursor / Cline / Continue

JSON 格式与 Claude Desktop 相同，配置路径则使用各客户端的 MCP 配置路径。

工具

Ichiba（4 个）

工具	功能
ichiba_item_search	在 Rakuten Ichiba 中按关键词搜索，并支持价格筛选、排序以及按品类 / 商店限制。
ichiba_genre_search	浏览品类树。返回当前品类、祖先、同级品类和子品类。
ichiba_item_ranking	实时畅销商品排名：总体排名、按品类排名，或按年龄 / 性别排名（根据乐天规定，品类和人口统计信息不能同时使用）。
ichiba_product_search	Item Price Navi：搜索多个卖家的同一商品，并返回最低 / 最高 / 平均价格。

ichiba_tag_search 已于 1.3.0 移除：乐天已停用 Tag Search 端点。

Books（9 个）

只有 books_total_search 支持自由文本搜索。各分类工具按标题 / 作者 / 艺术家 / JAN / ISBN / 品类搜索，因为乐天的端点只接受这些条件。

工具	功能
books_total_search	搜索整个 Rakuten Books 的所有分类。
books_book_search	按标题、作者、ISBN、出版社搜索纸质书籍。
books_cd_search	按标题、艺术家、唱片公司、JAN 搜索音乐 CD。
books_dvd_search	搜索 DVD / Blu-ray。
books_foreign_book_search	搜索非日语书籍。存在译本时返回 japaneseTitle。
books_magazine_search	按标题、出版社、JAN 搜索杂志。
books_game_search	按标题、硬件平台、JAN 搜索电子游戏。
books_software_search	按标题、操作系统、JAN 搜索计算机软件。
books_genre_search	浏览 Books 品类树（000 = 顶级品类）。

旅行（7）

工具	功能
travel_simple_hotel_search	按地区代码或经纬度搜索酒店。
travel_vacant_hotel_search	搜索指定入住和退房日期有空房的酒店。返回住宿方案，包含每晚价格和 chargeBasis（per_person 或 per_room）。
travel_hotel_detail_search	按 hotelNo 查询一家酒店的完整详情。
travel_get_area_class	地区代码层级：日本 → 47 个都道府县 → 城市 → 区域。
travel_keyword_hotel_search	按名称、地标或地区进行酒店全文搜索。
travel_get_hotel_chain_list	获取 Rakuten Travel 上登记的全部 307 个酒店连锁品牌。
travel_hotel_ranking	按排名类别获取热门酒店（全部／温泉／日式旅馆／城市／度假村／商务／膳宿公寓／公共旅馆）。

食谱（2）

工具	功能
recipe_category_list	完整的 Rakuten Recipe 分类树（43 个大类 → 约 540 个中类 → 约 1500 个小类）。传入 level 可获取某一层级。
recipe_category_ranking	获取某个分类中的热门食谱，包含标题、食材列表、准备时间、费用估算、图片和作者。

Kobo（2）

工具	功能
kobo_ebook_search	搜索 Rakuten Kobo 的电子书目录。返回标题、系列、作者、出版商、语言代码、价格和销售页面 URL。
kobo_genre_search	浏览 Kobo 的类别树。顶级类别为 101（电子书）。

GORA（3）

工具	功能
gora_golf_course_search	按地区代码、关键词或坐标搜索高尔夫球场。
gora_golf_course_detail	获取球场完整档案：设计师、球洞／标准杆、球场距离、果岭类型、着装要求、设施和基础价格。
gora_plan_search	搜索指定打球日期的预约方案。返回各方案价格、球车／球童／午餐是否包含，以及人数限制。

示例查询

楽天で1万円以下のワイヤレスイヤホンを探して。レビュー4以上。
村上春樹の楽天Kobo電子書籍を新着順で。
東京駅近くのホテル、7月1〜2日、2名で1泊1万5千円以下の空室。
今週末東京近郊のゴルフ場で安いプランは？
楽天レシピで人気の鶏胸肉料理を5件、材料と所要時間込みで。
JANコード 4988601009447 のCDの取扱店舗。

架构

采用模块化设计：src/tools/ 下每个 API 系列对应一个文件。支持 Stdio 和 HTTP 传输。采用包含 9 个错误类别的类型化错误树，涵盖 Config / Auth / IpNotAllowed / RateLimit / Server / NotFound / BadRequest / MalformedResponse / Unknown。遇到 429 和 5xx 时采用带退避的重试机制，并将 Retry-After 解析为秒数或 HTTP 日期。架构简介、规范以及添加新工具的方法，请参阅 AGENTS.md。

安全

全部 27 个工具都只通过 HTTP GET 请求调用 Rakuten Web Service API，不会创建、修改或删除任何内容。适用 Rakuten 的服务条款和速率限制。返回的条目均为促销信息，采取行动前请在 Rakuten 上核实价格和库存情况。

免责声明

本项目为非官方项目，与 Rakuten Group, Inc. 无关联，也未获其认可或赞助。Rakuten、Rakuten Ichiba、Rakuten Books、Rakuten Travel、Rakuten Recipe、Rakuten Kobo 和 Rakuten GORA 均为 Rakuten Group, Inc. 的商标。使用风险自负。

许可证

MIT