Dida Hotel MCP — Hotel Search & Booking

DIDA Hotel MCP Server Global is designed specifically for global users and international travel scenarios.

💡 For Chinese users or workflows primarily targeting the mainland China market and local payment systems, please refer to the localized version: 👉 Dida-hotel-MCP-CN

An official Model Context Protocol (MCP) server that empowers AI Agents to search, compare, and book over 2 Million hotels globally. Powered by DIDA (Asia's #1 and world's #3 B2B travel platform), this server bridges the gap between AI travel recommendations and real-world bookings.

🏠 Partner Center · 🚀 Quick Start · 🔧 Available Tools · 📚 Usage Examples · 💬 Support

---

🌟 Why DIDA Hotel MCP Server Global?

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

• 🏨 2M+ Global Hotels: Deep coverage of major destinations worldwide, returning multilingual room details.
• ⚡ 110K+ Direct Partner Rates: Live inventory checks, rate locks, and cancellation policy checks, ensuring the agent recommendations are bookable in real-time.
• 💰 Monetization Ready: Configure your own markups in the DIDA Partner Center. When users book via your AI assistant, you earn commissions directly.
• 🔌 Client-Ready: Instant integration with Cursor, Claude Desktop, Windsurf, ChatGPT, and other MCP-compliant applications.

---

🎯 Target Use Cases

• 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

1. Go to the DIDA Partner Center and sign up for a free key.
2. Fill in your basic information. Approval is automated and takes 1–3 minutes. You will receive an email containing:
   • Your mcp_ prefixed API Key.
   • Credentials for your B2B Partner Center dashboard (to monitor orders, configure markup, and track earnings).

---

Step 2: Running the Server

Choose one of the methods below to run the server.

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

If you have uv installed, run the server instantly:

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

Method B: Standard Python Setup

# 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.

---

⚙️ MCP Client Configuration

1. Claude Desktop (Stdio / Local Subprocess)

Best for local desktop workflows. Add this to your Claude Desktop configuration file (typically ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dida-hotel-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/dida_hotel_mcp_global/server.py"],
      "env": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

(Make sure to replace /absolute/path/to/... and YOUR_API_KEY with your actual local path and key).

2. Cursor / Windsurf (SSE / HTTP Transport)

Add the local server URL under Cursor's MCP Settings page:

• Name: Dida-Hotel-MCP
• Type: SSE
• URL: http://localhost:8000/mcp
• Headers (JSON):

  {
    "Authorization": "Bearer YOUR_API_KEY",
    "Accept-Language": "en_US"
  }
  

---

🔧 Available 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.

<details> <summary><b>🔎 View Detailed Input Parameters (checkInParam, filterOptions, hotelTags)</b></summary>

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).

</details>

<details> <summary><b>📄 View Response JSON Schema Example</b></summary>

{
  "message": "Hotel search succeeded",
  "hotelInformationList": [
    {
      "hotelId": 43615,
      "bookingUrl": "https://rollinggo.cn/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.

</details>

---

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.

<details> <summary><b>🔎 View Detailed Input Parameters (dateParam, occupancyParam, localeParam)</b></summary>

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.

</details>

<details> <summary><b>📄 View Response JSON Schema Example</b></summary>

{
  "success": true,
  "errorMessage": null,
  "hotelId": 43615,
  "bookingUrl": "https://rollinggo.cn/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.

</details>

---

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.

<details> <summary><b>📄 View Response JSON Schema Example</b></summary>

{
  "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

</details>

---

📚 Usage Examples

<details> <summary><b>Example 1: City Search</b></summary>

{
  "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
}

</details>

<details> <summary><b>Example 2: With Tags and Budget Constraints</b></summary>

{
  "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
}

</details>

<details> <summary><b>Example 3: Query Hotel Room Types and Pricing</b></summary>

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

</details>

---

🔑 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.

---

💬 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.

<img src="discord-qr.png" width="300" alt="Discord Support" />

---

Made with ❤️ by the DIDA Team