Comprehensive Travel & Hospitality MCP Server (hotel_search)

A unified FastMCP server providing parallel hotel accommodations, gourmet dining and cafe searches (Tabelog Japan), multi-modal transit & routing, and verified traveler/diner reviews across global and regional platforms.

Key Capabilities

🏨 Accommodations & Hotels

• 🔄 Parallel Multi-Provider Search: Query Agoda, Booking.com, and Hotels.com simultaneously with search_hotels(..., provider="all").
• 🔑 Silent Chrome Authentication: Seamlessly loads user sessions for Agoda (VIP tier), Booking.com (Genius tier), and Hotels.com (OneKey rewards).
• ⚖️ Cross-Platform Price Comparison: Compare live rates across all three platforms in parallel using compare_hotel_prices(...) to find the cheapest provider.
• 🛏️ Room Grid & Rate Packages: Inspect bed configurations, room sizes, breakfast inclusions, cancellation policies, and rates.

🍽️ Dining, Restaurants & Cafes (Tabelog Japan)

• 🍣 Gourmet Search & Ranking: Search restaurants with Bayesian score curves (>=3.50 top 3%, >=4.00 legendary/Michelin tier) via search_restaurants(...) / search_tabelog(...).
• 🏆 Award Winner Highlights: Filter and highlight The Tabelog Award winners (Gold, Silver, Bronze) and Tabelog 100 Famous Stores (Hyakumeiten).
• 🍱 Budget & Amenities: Separate lunch vs. dinner budgets, multilingual menus, private dining rooms, and barrier-free access.
• 📅 Live Vacancy Calendar: Check open reservation dates via check_restaurant_reservation(...).

🧭 Multi-Modal Transit & Navigation

• 🚶🚇🚕 Directions & Fares: Calculate walking routes, public transit (subway/bus line names and transfers), and taxi fares via get_transit_and_directions(...).

⭐ Verified Place Reviews

• 💬 Cross-Platform Reviews: Retrieve review scores, star distributions, and traveler feedback from Google Reviews, Kakao Maps, and Tabelog via get_place_reviews(...).

---

Project Structure

hotels-mcp/
├── pyproject.toml        # PEP 517/518 build config, dependencies & CLI entrypoints
├── README.md             # Documentation & usage guide
├── AGENTS.md             # Agent guidelines & GitNexus code intelligence
├── CLAUDE.md             # Claude developer instructions
├── tests/
│   ├── __init__.py
│   └── test_server.py    # 17 live multi-provider integration test suites
└── src/
    └── travel_mcp/
        ├── __init__.py   # Package root
        ├── __main__.py   # CLI entrypoint (`python -m travel_mcp`)
        ├── server.py     # FastMCP server instance, tools, prompts & resources
        ├── models.py     # Normalized Pydantic DTOs for travel, dining, and transit
        └── providers/
            ├── __init__.py         # Unified provider factory & registry
            ├── accommodations/     # Hotel accommodation providers
            │   ├── __init__.py
            │   ├── base.py         # HotelProvider ABC & session loader
            │   ├── agoda.py        # Agoda accommodation provider
            │   ├── booking.py      # Booking.com accommodation provider
            │   └── hotels_com.py   # Hotels.com accommodation provider
            ├── dining/             # Restaurant & cafe providers
            │   ├── __init__.py     # Dining provider factory
            │   ├── base.py         # DiningProvider ABC
            │   └── tabelog.py      # Tabelog client & vacancy parser
            ├── routes/             # Multi-modal routing providers
            │   ├── __init__.py     # Route provider factory
            │   ├── base.py         # RouteProvider ABC
            │   └── kakao.py        # Kakao Maps routing provider
            └── reviews/            # Unified place review providers
                ├── __init__.py     # Review provider registry
                ├── base.py         # ReviewProvider ABC
                ├── agoda.py        # Agoda reviews provider
                ├── google.py       # Google Reviews provider
                ├── kakao.py        # Kakao Place reviews provider
                └── tabelog.py      # Tabelog reviews provider

---

Installation & Setup

cd /Users/richardluo/Developer/hotels-mcp
uv sync

Run Tests:

uv run python tests/test_server.py

Run Server:

uv run travel-mcp
# or
uv run python -m travel_mcp

---

Antigravity / MCP Configuration

Add to ~/.gemini/config/mcp_config.json or your workspace .agents/mcp_config.json:

{
  "mcpServers": {
    "travel_mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/richardluo/Developer/hotels-mcp",
        "run",
        "python",
        "-m",
        "travel_mcp"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

---

Available Tools

🍽️ Dining, Restaurants & Cafes

Tool	Parameters	Description
search_restaurants	query, prefecture=None, area=None, genre=None, sort_by='rating', meal_type='all', provider='tabelog', page=1, limit=10	Searches top-rated restaurants across Japan on Tabelog (tabelog.com). Includes Bayesian scores (3.5+ top 3%, 4.0+ legendary), Award winners (Gold/Silver/Bronze), Hyakumeiten (100 Famous Stores), lunch/dinner budgets, and booking status.
get_restaurant_details	restaurant_id_or_url, provider='tabelog'	Fetches complete restaurant profile, award history, exact address, GPS coordinates, phone, budget, amenities, and high-res food photos.
suggest_dining	query, provider='tabelog', limit=5	Autocompletes search keywords for restaurants, stations, areas, and food genres.
check_restaurant_reservation	restaurant_id, provider='tabelog'	Checks live upcoming online booking vacancy calendar and available reservation dates for a restaurant.
search_tabelog	(same as search_restaurants)	Direct shortcut to Tabelog restaurant search.
get_tabelog_restaurant_details	(same as get_restaurant_details)	Direct shortcut to Tabelog restaurant profile.
suggest_tabelog	(same as suggest_dining)	Direct shortcut to Tabelog autocomplete.
check_tabelog_reservation	(same as check_restaurant_reservation)	Direct shortcut to Tabelog vacancy calendar.

🧭 Multi-Modal Transit & Routing

Tool	Parameters	Description
get_transit_and_directions	origin, destination, travel_mode='all', country='KR', provider=None	Calculates walking steps, public transit (subway/bus lines, transfers, fares), and driving taxi fares between any two places (hotels, restaurants, cafes, stations, airports).
get_hotel_distance_and_transit	origin, destination, travel_mode='all', country='KR', provider=None	Alias for get_transit_and_directions.

⭐ Place & Venue Reviews

Tool	Parameters	Description
get_place_reviews	place_or_hotel, provider='kakao', page=1, page_size=10	Fetches verified user reviews, star distributions, and reviewer feedback from Kakao Maps, Google Reviews (provider='google'), or Tabelog (provider='tabelog').

🏨 Accommodations & Hotels

Tool	Parameters	Description
search_hotels	query, check_in, check_out, adults=2, children=0, rooms=1, min_price=None, max_price=None, provider='all', logged_in=True, limit=10	Searches Agoda, Booking.com, and/or Hotels.com in parallel with date, occupancy, and price filters.
compare_hotel_prices	hotel_name, check_in, check_out, adults=2, rooms=1	Runs a 3-way parallel price check across Agoda, Booking.com, and Hotels.com to find the cheapest rate.
suggest_locations	query, provider='all', limit=5	Autocompletes destination cities, districts, landmarks, and properties across Agoda, Booking.com, and Hotels.com.
get_property_details	hotel_id, provider='agoda', check_in=None, check_out=None, adults=2, children=0, rooms=1, logged_in=True	Fetches property overview, address, amenities, and policies.
get_room_grid	hotel_id, provider='agoda', check_in="", check_out="", adults=2, children=0, rooms=1, logged_in=True	Inspects room types, bed setups, breakfast inclusion, cancellation policies, and rates.
get_hotel_reviews	hotel_id, provider='agoda', page=1, page_size=10	Fetches verified traveler reviews and category scores.
get_hotel_faq	hotel_id, provider='agoda'	Retrieves official verified hotel FAQs.
get_login_status	provider='all'	Checks active authentication for Agoda (VIP), Booking.com (Genius), and Hotels.com (OneKey).
interactive_login	provider='agoda'	Opens Chrome to sign-in portal if session expired (supports 'agoda', 'booking.com', or 'hotels.com').

---

MCP Prompts & Resources (MCP 2.0)

Prompts

• plan_trip_itinerary(destination, check_in, check_out, adults, dining_preferences): End-to-end trip planning combining hotels, dining recommendations, and transit routes.
• search_japan_dining(query, prefecture, genre, meal_type): Discover top-rated dining spots and award winners in Japan.
• compare_hotel_deals(hotel_name, check_in, check_out, adults, rooms): 3-way price comparison and perk evaluation.
• search_destination_hotels(destination, check_in, check_out, adults, rooms): Search and rank accommodations.

Resources

• travel://providers (and hotels://providers): Registry of accommodation, dining, routing, and review providers.
• travel://capabilities: Full capability breakdown across all travel domains.
• travel://status (and hotels://status): Live session & cookie health across all providers.