Rakuten Travel

Search for hotels and check their availability using the Rakuten Travel API.

GitHub

Rakuten Travel MCP Server

A Model Context Protocol (MCP) server that provides an interface to the Rakuten Travel API for hotel searching and availability checking.

Features

  • Hotel Search: Search for hotels by location, hotel number, or area code
  • Availability Search: Find vacant hotels with real-time availability
  • Area Code Resource: Access hierarchical Japanese location data
  • Type-Safe: Comprehensive TypeScript types with Zod validation
  • MCP Compliant: Works with any MCP-compatible client

Prerequisites

Installation

  1. Clone the repository:
git clone https://github.com/yourusername/rakuten_travel_mcp.git
cd rakuten_travel_mcp

Usage

Running the Server

  1. configure your MCP client. (following example is for Claude Desktop)
```json
{
    "mcpServers": {
        "rakuten_travel_mcp": {
            "command": "deno",
            "args": [
                "run",
                "--allow-net=app.rakuten.co.jp",
                "--allow-env=APPLICATION_ID",
                "/path/to/rakuten_travel_mcp/serve.ts"
            ],
            "env": {
                "APPLICATION_ID": "<your_application_id>"
            }
        }
    }
}

Available Tools

1. Hotel Search (hotel-search)

Search for hotels using various criteria:

Search by Hotel Number:

{
  "hotelNo": ["123456", "789012"]
}

Search by Coordinates:

{
  "latitude": 35.6762,
  "longitude": 139.6503,
  "searchRadius": 3,
  "datumType": 1
}

Search by Area Code:

{
  "largeClassCode": "japan",
  "middleClassCode": "tokyo",
  "smallClassCode": "shibuya"
}

2. Vacant Hotel Search (vacant-hotel-search)

Search for available hotels:

{
  "checkinDate": "2024-03-15",
  "checkoutDate": "2024-03-17",
  "rooms": 1,
  "adultNum": 2,
  "largeClassCode": "japan",
  "middleClassCode": "tokyo"
}

Available Resources

Area Code Resource (config://area_code)

Access hierarchical location data for Japan:

  • Country level (e.g., "japan")
  • Prefecture level (e.g., "tokyo", "osaka")
  • City level (e.g., "shibuya", "shinjuku")
  • Area level (detailed districts)

Development

Running Tests

# Run all tests
deno task test

# Run tests in watch mode
deno task test:watch

Project Structure

rakuten_travel_mcp/
├── serve.ts           # Main MCP server implementation
├── types.ts           # TypeScript types and Zod schemas
├── area_code.json     # Hierarchical location data
├── *.test.ts          # Test files
├── deno.json          # Deno configuration
└── .env              # Environment variables (create this)

API Parameters

Common Parameters

  • hits: Number of results per page (1-30, default: 30)
  • page: Page number for pagination
  • sort: Sort order (various options available)

Hotel Search Specific

  • hotelNo: Array of hotel numbers
  • latitude/longitude: Coordinates for geographic search
  • searchRadius: Search radius in km (1-3)
  • squeezeCondition: Filter for hotels with/without vacancies
  • hotelType: Filter by hotel type (0-3)

Vacant Hotel Search Specific

  • checkinDate/checkoutDate: Required dates (YYYY-MM-DD)
  • rooms: Number of rooms (1-5)
  • adultNum: Adults per room (1-5)
  • minCharge/maxCharge: Price range filters

Testing

The project includes comprehensive tests for:

  • Schema validation
  • API parameter building
  • Response processing
  • Error handling
  • Network timeouts

Error Handling

The server handles various error scenarios:

  • Missing required parameters
  • Invalid date formats
  • API rate limits
  • Network timeouts
  • Invalid API responses

Contributing

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

Serveurs connexes