io.github.RollingGo-AI/hotelbooking-ai

Official

by RollingGo-AI · Python

RollingGo Hotel Booking MCP Server (Global/AI Edition)

io.github.RollingGo-AI/hotelbooking-ai — Model Context Protocol (MCP) Server

RollingGo Hotel Booking MCP Server (Global/AI Edition) provides an MCP server interface for hotel booking capabilities. It is associated with model-context-protocol and focuses on function/tool calling patterns for AI agents interacting with a hotel booking API, within travel-related workflows.

🛠️ Key Features

Model Context Protocol (MCP)
Function/tool calling support
Hotel booking API integration
AI agent workflow alignment (agentic-workflows, ai-agents)

🚀 Use Cases

Hotel search and booking flows via a hotel-mcp interface
Travel-api–driven agent workflows (dida-travel, travel-api)
Agentic booking operations using tool-calling

⚡ Developer Benefits

Compatible with MCP server ecosystem (claude-mcp, codex-mcp, cursor-mcp, windsurf-mcp)
Function-calling and tool-calling structure for AI integrations
Clear alignment with hotel-booking-api and booking-engine needs

⚠️ Limitations

No tool count or capabilities details are provided in the source data.

Topics

agentic-workflowsai-agentsbooking-enginechatgptclaude-mcpclaude-mcp-servercodex-mcpcursor-mcpdida-travelfunction-callinghotel-booking-apihotel-mcpmcpmcp-servermodel-context-protocolmodel-context-protocol-serverstool-callingtravel-apiwindsurf-mcp

README.md21 KBView on GitHub

RollingGo Hotel MCP — Hotel Search & Booking

🏠 Apply Key · 🚀 Quick Start · 📚 Examples · 💬 Support · 🔍 Q&A · 💰Earn with RollingGo

This is an official MCP server empowers AI Agents to search, compare, and book over 2 Million hotels globally; this server bridges the gap between AI travel recommendations and real-world bookings.

Service	Endpoint	Available Tools	Authentication
Hotel MCP	`https://mcp.rollinggo.ai/mcp`	searchHotels, getHotelDetail, getHotelSearchTags	`Authorization: Bearer <YOUR_API_KEY>`

Transport Protocol: streamable-http
Pricing: Completely free, no usage limits
Access Method: Self-service following this documentation; suitable for rapid prototyping and tool development.

RollingGo MCP also offers an OAuth 2.0 Authorization Code flow, providing 7 tools including getHotelSearchTags, searchHotels, getHotelDetail, hotelPriceConfirm, searchHotelOrders, and more. This mode is designed for deep integration with enterprise-grade production applications and requires a business contact via contact@rollinggo.ai.

For Chinese users or workflows primarily targeting the mainland China market and Alipay payment systems, please refer to this version: RollingGo-hotel-MCP-CN

🌟 Why DIDA Hotel MCP?

Traditional AI agents can only recommend hotels based on static training datasets. The RollingGo Hotel MCP equips your LLM agent with direct, real-time transactional capabilities:

✅ Live Rates & Bookable Inventory — Zero-latency price verification; every result is instantly bookable.

✅ Supply Chain — Fully API-native end-to-end.

✅ Global Hotel Network — 2,000,000+ properties covering 200+ countries/regions. 500+ suppliers covering every tier, from luxury chains to local boutiques.

✅ Direct Contracts — 110,000+ directly connected hotels with live price and inventory sync.

✅ Price Edge at Source — Priced upstream of OTAs; sharp rates on hot spots.

✅ Agent-Ready — Works with 40+ leading agents: Cursor, Claude Code, Codex, Windsurf, Copilot, and more.

✅ Earn your Revenue on Every MCP Call — Set country-specific markups, earn commission on every completed booking, and track your orders, earnings, and payouts in real time. Flexible withdrawals for both businesses and individual developers.

🎯 Who is it for

• Companies or individual developers building AI Agents

• Developers looking to integrate hotel booking capabilities into MCP Clients

• Developers building travel planning, business travel management, OTA, and lifestyle service agents

• Product teams seeking to validate AI Agent commercial transaction loops

• Individuals with needs for hotel search, price comparison, and price drop alerts******

🎯 Use Cases

General-Purpose Agents: Equip any AI agent with native hotel booking. Users can compare, filter, and book—all within a single natural-language conversation.
AI Travel Planners: Integrate hotel searching directly into natural language itineraries.
Corporate Travel Assistants: Allow employees to query, compare, and book business travel within Slack, Teams, or custom chat interfaces.
Transactional Demos: Validate end-to-end AI agent commerce and payment flows without heavy backend integration.

🚀 Quick Start

Integrate global hotel search and booking into your AI assistant in under 5 minutes with no coding required.

Step 1: Get Your Developer API Key

Go to the DIDA Partner Center and sign up for a free key.
You will receive an email containing: Credentials for your B2B Partner Center dashboard (to monitor orders, configure markup, and track earnings).

Step 2: Connect to Your Agent

Recommended clients: Claude CLI, Codex, and Cursor. Other MCP-compatible clients (such as Kiro, Doubao, etc.) can be configured similarly.

Claude CLI

Create .mcp.json in your project root:

json

{
  "mcpServers": {
    "Dida-Hotel": {
      "url": "https://mcp.rollinggo.ai/mcp",
      "type": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Or add directly via the command line:

bash

claude mcp add \
  --transport http \
  --header "Authorization: Bearer YOUR_API_KEY" \
  Dida-Hotel \
  https://mcp.rollinggo.ai/mcp

Codex

Config file location: .codex/config.json in the project root, or globally at ~/.codex/config.json

json

{
  "mcpServers": {
    "Dida-Hotel": {
      "url": "https://mcp.rollinggo.ai/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Cursor

Config file location: .cursor/mcp.json in the project root, or globally at ~/.cursor/mcp.json

json

{
  "mcpServers": {
    "Dida-Hotel": {
      "url": "https://mcp.rollinggo.ai/mcp",
      "type": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Replace YOUR_API_KEY with your actual API Key.

Test Directly with cURL

Note: cURL must include -H "Accept: application/json, text/event-stream", otherwise the server will return a 400 error.

bash

curl -X POST https://mcp.rollinggo.ai/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "searchHotels",
      "arguments": {
        "originQuery": "Shanghai Bund five-star hotel",
        "place": "Shanghai Bund",
        "placeType": "Attraction",
        "checkInParam": {
          "checkInDate": "2026-06-01",
          "stayNights": 2
        },
        "filterOptions": {
          "starRatings": [5.0]
        },
        "size": 3
      }
    },
    "id": 1
  }'

Step 3: Your First MCP Call

Once configured, simply tell your AI assistant:

"Find me a five-star hotel near the Shanghai Bund for a stay starting the day after tomorrow."

The AI will automatically call the searchHotels Tool and return a list of hotels.

Hotel Search Example

json

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "searchHotels",
    "arguments": {
      "originQuery": "Shanghai Bund five-star hotel",
      "place": "Shanghai Bund",
      "placeType": "Attraction",
      "checkInParam": {
        "checkInDate": "2026-06-01",
        "stayNights": 2
      },
      "filterOptions": {
        "starRatings": [5.0]
      },
      "size": 3
    }
  },
  "id": 1
}

Step 4: View Results and Sample Data

Hotel Search Results (Real Data)

Searching for "Shanghai Bund five-star hotel", 2 nights, returns:

Hotel	Stars	Lowest Price/Night	Distance to Bund
Fairmont Peace Hotel Shanghai	⭐⭐⭐⭐⭐	$648	124m
The Peninsula Shanghai	⭐⭐⭐⭐⭐	$940	252m

Expected Response JSON Example

json

{
  "message": "Hotel search successful",
  "hotelInformationList": [
    {
      "hotelId": 29529,
      "bookingUrl": "https://rollinggo.ai/pages/hotel/detail/index?...",
      "name": "Fairmont Peace Hotel on the Bund",
      "address": "No. 20 Nanjing East Road",
      "starRating": 5.0,
      "price": {
        "message": "Price query successful. Lowest price: 648, Currency: USD",
        "hasPrice": true,
        "currency": "USD",
        "lowestPrice": 648.0
      },
      "hotelAmenities": ["Bar", "Gym", "Pool", "SPA", "Parking", "WIFI"],
      "tags": ["SPA Service", "Resort Hotel", "Sports-Friendly Hotel"]
    }
  ]
}

🔧 Available Tools

Official Docs | Dida MCP Tools

The server registers 3 core tools to handle the complete search-to-book lifecycle:

1) searchHotels

Find hotels by location, date, price, star rating, and tags.

Input Parameters:
- originQuery (string, required): User's raw text request (e.g., "Find boutique hotels in Tokyo under $200").
- place (string, required): Specific destination, attraction, or airport name.
- placeType (string, required): Location type (city, airport, point_of_interest, hotel, etc.). Supported values: city, airport, point_of_interest, train_station, subway_station, hotel, district/county, detailed address.
- countryCode (string, optional): ISO 3166-1 alpha-2 country code, e.g. CN, US.
- size (number, optional, default: 5): Number of hotels to return, max 20.
- checkInParam (object, optional): Check-in related parameters.
- filterOptions (object, optional): Filter parameters.
- hotelTags (object, optional): Tag / brand / budget filters.

🔎 View Detailed Input Parameters (checkInParam, filterOptions, hotelTags)

checkInParam fields:

adultCount (number, optional, default: 2): Adults per room.
checkInDate (string, optional, format: YYYY-MM-DD): Check-in date. If omitted, in the past, or malformed, defaults to tomorrow.
stayNights (number, optional, default: 1): Number of nights (max 28).

filterOptions fields:

distanceInMeter (number, optional): Straight-line distance from POI in meters. Defaults to 2000 when a POI is used.
starRatings (number[], optional): Star rating range, defaults to [0.0, 5.0], step 0.5.

hotelTags fields:

requiredTags (string[], optional): Required tags (hard constraint).
preferredBrands (string[], optional): Preferred brands.
maxPricePerNight (number, optional): Max budget per night (CNY).

📄 View Response JSON Schema Example

json

{
  "message": "Hotel search succeeded",
  "hotelInformationList": [
    {
      "hotelId": 43615,
      "bookingUrl": "https://rollinggo.ai/pages/hotel/detail/index?...",
      "name": "Sunworld Dynasty Hotel Beijing",
      "brand": null,
      "address": "50 Wangfujing Street",
      "destinationId": "6140156",
      "latitude": 39.917748,
      "longitude": 116.412249,
      "distanceInMeters": 205,
      "starRating": 5.0,
      "price": {
        "message": "Price found, lowest: 626.0, currency: CNY",
        "hasPrice": true,
        "currency": "CNY",
        "lowestPrice": 626.0
      },
      "areaCode": "CN",
      "description": "...",
      "imageUrl": "https://image-cdn.RollingGo.com/...",
      "hotelAmenities": ["24h Front Desk", "WiFi"],
      "score": 1.0,
      "tags": ["Near Shopping Mall", "Free WiFi"]
    }
  ]
}

Note: price is an object, not a number. Fields may be missing or null depending on city/supply source.

2) getHotelDetail

Fetch real-time room types, dynamic pricing, inventory, and cancellation policies for a selected hotel.

Input Parameters:
- hotelId (number, optional): Hotel ID. Mutually exclusive with name; if both are provided, hotelId takes priority.
- name (string, optional): Hotel name (fuzzy match).
- dateParam (object, optional): Check-in / check-out date parameters.
- occupancyParam (object, optional): Guest count and room count parameters.
- localeParam (object, optional): Country and currency parameters.

🔎 View Detailed Input Parameters (dateParam, occupancyParam, localeParam)

dateParam fields:

checkInDate (string, optional, format: YYYY-MM-DD): Check-in date. Defaults to tomorrow if empty, malformed, or in the past.
checkOutDate (string, optional, format: YYYY-MM-DD): Check-out date. Defaults to checkInDate + 1 day if empty, malformed, or not after check-in.

occupancyParam fields:

adultCount (number, optional, default: 2): Adults per room.
childCount (number, optional, default: 0): Children per room.
childAgeDetails (number[], optional): Child ages, e.g. [3, 5].
roomCount (number, optional, default: 1): Number of rooms.

localeParam fields:

countryCode (string, optional, default: US): ISO 3166-1 alpha-2 country code.
currency (string, optional, default: USD): Currency code.

📄 View Response JSON Schema Example

json

{
  "success": true,
  "errorMessage": null,
  "hotelId": 43615,
  "bookingUrl": "https://rollinggo.ai/pages/hotel/detail/index?...",
  "name": "Sunworld Dynasty Hotel Beijing",
  "checkIn": "2026-03-05",
  "checkOut": "2026-03-06",
  "roomRatePlans": [
    {
      "roomTypeId": 4984714,
      "roomName": "Superior Room",
      "roomNameCn": "高级客房",
      "ratePlanId": "7012072001634754626",
      "ratePlanName": "Superior Room King Bed, 1 King Bed",
      "bedType": 73,
      "bedTypeDescription": "Unknown",
      "currency": "CNY",
      "totalPrice": 0,
      "totalSalesRate": null,
      "inventoryCount": null,
      "isOnRequest": null,
      "recommendIndex": null,
      "cancellationPolicies": [
        {
          "fromDate": "2026-03-02T10:00:00+08:00",
          "toDate": null,
          "amount": 634,
          "percent": null,
          "type": null,
          "description": null
        }
      ],
      "includedFees": null,
      "excludedFees": null,
      "metadata": null
    }
  ]
}

Note: On failure, the response may contain an error message (e.g. "Failed to fetch pricing, please retry later") or structured error fields. The roomRatePlans array can be long — consider paginating or limiting display on the client side.

3) getHotelSearchTags

Retrieve metadata containing all filterable tag names (e.g., "Free WiFi", "Gym", "Kid-Friendly") to refine search filtering. Suitable for local caching and client-side intent mapping.

📄 View Response JSON Schema Example

json

{
  "tags": [
    {
      "name": "Free WiFi",
      "category": "Core Amenities",
      "description": "Provides free WiFi"
    }
  ],
  "usageGuide": {
    "tagUsage": "Place tag names into hotelTags.preferredTags (preference), requiredTags (hard requirement), or excludedTags (exclusion)",
    "exampleRequest": "{...}"
  }
}

Common tag categories:

Brand & Ratings
Specialty Highlights
Core Amenities
Family & Kids
Service Details
Service & Dining
Transportation & Payment
Views & Room Types
Hotel Type
Pricing

📚 Usage Examples

Example 1: City Search

json

{
  "originQuery": "Find 4-star+ hotels in Beijing for 2 nights",
  "place": "Beijing",
  "placeType": "city",
  "checkInParam": {
    "checkInDate": "2026-03-01",
    "stayNights": 2
  },
  "filterOptions": {
    "starRatings": [4.0, 5.0]
  },
  "size": 5
}

Example 2: With Tags and Budget Constraints

json

{
  "originQuery": "Find quality hotels in Beijing with free WiFi, budget under 1000 per night",
  "place": "Beijing",
  "placeType": "city",
  "hotelTags": {
    "requiredTags": ["Free WiFi"],
    "maxPricePerNight": 1000
  },
  "size": 5
}

Example 3: Query Hotel Room Types and Pricing

json

{
  "hotelId": 43615,
  "dateParam": {
    "checkInDate": "2026-03-05",
    "checkOutDate": "2026-03-06"
  },
  "occupancyParam": {
    "adultCount": 2,
    "roomCount": 1
  },
  "localeParam": {
    "currency": "CNY",
    "countryCode": "CN"
  }
}

💬 Q&A

🔍Troubleshooting Guide

Q&A

Q1: The client doesn't show the Tool after configuration

Check if the JSON configuration format is correct
Confirm that url and type are correct
Confirm that the API Key in the Authorization header is correct
Restart the client (changes only take effect after restart)

Q2: Returns 401 Unauthorized Invalid or incorrectly formatted API Key:

The API Key should start with mcp_
In Authorization: Bearer YOUR_API_KEY, there must be a space after Bearer
Make sure there are no extra spaces or line breaks in the API Key

Q3: Returns 400 Bad Request Common when calling directly with cURL. Check that the Accept header is included:

bash

-H "Accept: application/json, text/event-stream"

Q4: searchHotels returns empty results

Check if place and placeType match (e.g., "Shanghai Bund" should be paired with "Attraction")
Relax filter criteria (remove star rating / tag restrictions)
Confirm that checkInDate is not in the past

Q5: Prices don't match actual rates Search results show reference prices; real-time prices may vary. Currently, only queries are supported — online booking is not yet available.

💬 Support

📧 Email: york.lu@dida.com
🐛 Issues: Submit issues or feature requests on GitHub Issues.
💬 Discord Community: Join our Discord Server or scan the QR code below to connect with other developers, discuss integrations, and get real-time support from the DIDA team.

🌟 Dida Hotel MCP (OAuth) v2.3 Major Update

v2.3 optimizes the order query structure and adds multiple order detail fields to help Agents better handle check-in, payment, and cancellation scenarios. Note: This update applies to the OAuth integration version only, not the API Key version documented herein. The OAuth version requires business onboarding contact@rollinggo.ai.

What changed

Unchanged tools (4)

getHotelSearchTags — Get all enabled hotel filter tags
searchHotels — Search global hotel list by conditions
getHotelDetail — Get available room types and pricing for a hotel
hotelPriceConfirm — Lock real-time final retail price for selected room

Modified tools (2)

createHotelBookingWithPaymentURL — Removed alipayUrlScene parameter; unified bookingResult.paymentUrl to generic checkout
searchHotelOrders — Output simplified to 9 core fields (orderNo, hotelName, roomName, orderStatus, totalPrice, etc.) for list view; full detail moved to dedicated tool

New tools (1)

getHotelOrderDetail — Query full structured order details by orderNo, including hotelConfirmationNo, guest list, bed type, contact phones, coordinates, payment/cancellation deadlines, and policy flags

New fields

hotelConfirmationNo — Hotel-side real confirmation number for front-desk lookup
stayInfo.bedTypeStr — Human-readable bed type description (e.g., "1 King Bed (1.8m)")
stayInfo.guestNames — Official pinyin/English guest name list for verification
priceInfo.paymentDeadline — Payment deadline timestamp (YYYY-MM-DD HH:mm:ss) for countdown alerts
policyInfo.freeCancelDeadline — Free cancellation deadline timestamp for refund window checks
policyInfo.isCancelable — Whether free cancellation is still available at the current moment

Tool count: 7 total (up from 6 in v2.2) — 1 new, 2 modified, 4 unchanged.

Appendix

🔣 If you want local deployment

Method A: Run via `uv` (Recommended - Zero Config Setup)

If you have uv installed, run the server instantly:

bash

uv run --with-requirements requirements.txt server.py

Method B: Standard Python Setup

bash

# Clone the repository
git clone https://github.com/DIDA-AI/dida_hotel_mcp_global.git
cd dida_hotel_mcp_global

# Setup virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies and run
pip install -r requirements.txt
python server.py

The local server will run on http://localhost:8000/mcp, automatically forwarding requests to the secure DIDA global API nodes.

🔑 Security & Headers

The local server forwards requests to the secure DIDA global API.
Always supply your API Key in the headers. Keys must start with mcp_.
Required header: Authorization: Bearer mcp_your_key_here

📜 License

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

Made with ❤️ by the DIDA Team

Install

Configuration

Environment variables

ROLLINGGO_API_KEYrequiredsecret

RollingGo Hotel API Key

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "hotelbooking-ai": {
      "command": "npx",
      "args": [
        "-y",
        "hotelbooking-ai@1.0.0"
      ],
      "env": {
        "ROLLINGGO_API_KEY": "<YOUR_ROLLINGGO_API_KEY>"
      }
    }
  }
}

io.github.RollingGo-AI/hotelbooking-ai — Model Context Protocol (MCP) Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

RollingGo Hotel MCP — Hotel Search & Booking

🌟 Why DIDA Hotel MCP?

🎯 Who is it for

🎯 Use Cases

🚀 Quick Start

Step 1: Get Your Developer API Key

Step 2: Connect to Your Agent

Claude CLI

Codex

Cursor

Test Directly with cURL

Step 3: Your First MCP Call

Hotel Search Example

Step 4: View Results and Sample Data

Hotel Search Results (Real Data)

Expected Response JSON Example

🔧 Available Tools

1) searchHotels

2) getHotelDetail

3) getHotelSearchTags

📚 Usage Examples

💬 Q&A

💬 Support

🌟 Dida Hotel MCP (OAuth) v2.3 Major Update

Unchanged tools (4)

Modified tools (2)

New tools (1)

New fields

Appendix

🔣 If you want local deployment

Method A: Run via uv (Recommended - Zero Config Setup)

Method B: Standard Python Setup

🔑 Security & Headers

📜 License

Install

Configuration

Method A: Run via `uv` (Recommended - Zero Config Setup)