rakuten-mcp

rakuten-mcp

Um servidor Model Context Protocol para a API Rakuten Web Service. 28 ferramentas somente leitura em seis famílias de produtos Rakuten: Ichiba (marketplace), Books, Travel, Recipe, Kobo e GORA (golfe).

Toda descrição de ferramenta é fornecida em inglês e japonês. Cada endpoint foi verificado contra a API Rakuten ao vivo em 04/06/2026 antes do lançamento.

Instalação

npm install -g rakuten-mcp

Ou npx rakuten-mcp sob demanda.

Configuração

1. Registre-se em Rakuten Web Service.
2. Crie um aplicativo. Você recebe um ID de Aplicativo UUID e uma Chave de Acesso com prefixo pk_.
3. Opcional: registre um ID de Afiliado para monetizar links de produtos. URLs de itens nas respostas das ferramentas o incluirão.

Variável	Obrigatória	Descrição
RAKUTEN_APP_ID	sim	ID do Aplicativo (formato UUID na nova plataforma)
RAKUTEN_ACCESS_KEY	sim	Chave de Acesso (começa com pk_)
RAKUTEN_AFFILIATE_ID	não	ID de Afiliado anexado a toda URL de item
RAKUTEN_MAX_RETRIES	não	Tentativas em 429 / 5xx. Padrão: 3.

Claude Desktop

Edite 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

Mesma estrutura JSON do Claude Desktop, no caminho de configuração MCP de cada cliente.

Ferramentas

Ichiba (5)

Ferramenta	O que faz
ichiba_item_search	Busca por palavras-chave no Rakuten Ichiba com filtros de preço, ordenação, restrições de gênero/loja.
ichiba_genre_search	Navegue pela árvore de gêneros. Retorna atual, ancestrais, irmãos e filhos.
ichiba_tag_search	Consulte uma tag específica por ID. Retorna o grupo e o nome da tag.
ichiba_item_ranking	Ranking de mais vendidos, geral ou por gênero / período / idade / sexo.
ichiba_product_search	Item Price Navi: mesmo produto em vários vendedores com preço mínimo/máximo/médio.

Books (9)

Ferramenta	O que faz
books_total_search	Busca entre categorias em todos os Rakuten Books.
books_book_search	Livros impressos por título, autor, ISBN, editora.
books_cd_search	CDs de música por título, artista, gravadora, JAN.
books_dvd_search	DVDs / Blu-ray.
books_foreign_book_search	Livros não japoneses. Retorna japaneseTitle quando existe uma tradução.
books_magazine_search	Revistas por título, editora, JAN.
books_game_search	Videogames por título, plataforma de hardware, JAN.
books_software_search	Software de computador por título, SO, JAN.
books_genre_search	Navegue pela árvore de gêneros de Books (000 = topo).

Travel (7)

Ferramenta	O que faz
travel_simple_hotel_search	Hotéis por código de área ou lat/lon.
travel_vacant_hotel_search	Hotéis com quartos disponíveis em datas específicas de check-in / check-out. Retorna planos com preços por noite e total.
travel_hotel_detail_search	Detalhes completos de um hotel por hotelNo.
travel_get_area_class	A hierarquia de códigos de área: 日本 → 47 prefeituras → cidades → distritos.
travel_keyword_hotel_search	Busca de hotéis por texto livre: nome / ponto de referência / área.
travel_get_hotel_chain_list	Todas as 307 redes de hotéis registradas no Rakuten Travel.
travel_hotel_ranking	Melhores hotéis por gênero de ranking (todos / onsen / ryokan / cidade / resort / negócios / pensão / publichouse).

Recipe (2)

Ferramenta	O que faz
recipe_category_list	A árvore completa de categorias do Rakuten Recipe (43 grandes → ~540 médias → ~1500 pequenas). Passe level para buscar um nível.
recipe_category_ranking	Receitas principais em uma categoria com título, lista de ingredientes, tempo de preparo, custo estimado, imagem e autor.

Kobo (2)

Ferramenta	O que faz
kobo_ebook_search	Busca no catálogo de eBooks do Rakuten Kobo. Retorna título, série, autor, editora, código de idioma, preço e URL de venda.
kobo_genre_search	Navegue pela árvore de gêneros do Kobo. O nível superior é 101 (電子書籍).

GORA (3)

Ferramenta	O que faz
gora_golf_course_search	Campos de golfe por código de área, palavra-chave ou coordenadas.
gora_golf_course_detail	Perfil completo do campo: designer, buracos/par, distância do campo, tipo de grama, código de vestimenta, instalações, preços base.
gora_plan_search	Planos de reserva em uma data específica de jogo. Retorna preços por plano, inclusões de carrinho/caddie/almoço, restrições de número de jogadores.

Exemplos de consultas

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

Arquitetura

Modular: um arquivo por família de API em src/tools/. Transportes Stdio e HTTP ambos suportados. Árvore de erros tipada com 8 classes cobrindo Config / Auth / RateLimit / Server / NotFound / BadRequest / MalformedResponse / Unknown. Nova tentativa com backoff em 429 e 5xx, analisa Retry-After como segundos e data HTTP. Veja AGENTS.md para o resumo da arquitetura, convenções e como adicionar uma nova ferramenta.

Segurança

Todas as 28 ferramentas são GETs HTTP somente leitura contra a API Rakuten Web Service. Nenhuma ferramenta cria, modifica ou exclui nada. Os termos de serviço e limites de taxa da Rakuten se aplicam. Os itens retornados são listagens promocionais — verifique preços e disponibilidade na Rakuten antes de agir com base neles.

Aviso legal

Não oficial. Não afiliado, endossado ou patrocinado pela Rakuten Group, Inc. Rakuten, Rakuten Ichiba, Rakuten Books, Rakuten Travel, Rakuten Recipe, Rakuten Kobo e Rakuten GORA são marcas registradas da Rakuten Group, Inc. Use por sua conta e risco.

Licença

MIT