hirochachacha/rakuten_travel_mcp

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

• Deno runtime installed
• Rakuten Travel API Application ID (Get one here)

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

• Built with Model Context Protocol SDK
• Powered by Rakuten Travel API