Tatilsepeti Hotel Search MCP Server

Model Context Protocol (MCP) server for Tatilsepeti hotel search, detail, room and review functionality. API sözleşmesi, Tatilsepeti mobil uygulamasının kullandığı gerçek endpoint'lerle (/api/v1, /api/v2) birebir uyumludur.

Features

• Destinasyon arama — bölge/lokasyon bul
• Otel listeleme — sıralama, fiyat aralığı ve kampanya filtreleriyle
• Otel detayı — açıklama, olanaklar, konum
• Oda listesi — müsait oda tipleri ve fiyatları
• Otel yorumları — Tatilsepeti ve TripAdvisor kaynaklı
• Statik token auth — expire olmayan bir token ile sabit Bearer header

Installation

Using npx (Recommended)

npx @tatil/hotel-mcp

From Source

npm install
# or
yarn install

Configuration

⚠️ Breaking change (v0.2.0): API_URL artık versiyonsuz kök domain olmalı (örn. /api/v1 eklemeyin). Sebep: mobil uygulama otel listesini v2, geri kalan otel endpoint'lerini v1 üzerinden çağırıyor; server artık her istek için doğru versiyonu kendisi ekliyor.

Create a .env file or set environment variables:

API_URL=https://api.tatilsepeti.com
API_TOKEN=your_static_api_token
BASE_URL=https://www.tatilsepeti.com

Or export directly:

export API_URL="https://api.tatilsepeti.com"
export API_TOKEN="your_static_api_token"
export BASE_URL="https://www.tatilsepeti.com"

API_TOKEN, expire olmayan sabit bir Bearer token'dır — her istekte Authorization: Bearer <API_TOKEN> olarak gönderilir. Token expire olan türden ise (kısa ömürlü OAuth token'ı), bu server onu otomatik yenilemez; expire olmayan bir token kullanılmalı.

Usage

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tatilsepeti-hotel": {
      "command": "npx",
      "args": ["@tatil/hotel-mcp"],
      "env": {
        "API_URL": "https://api.tatilsepeti.com",
        "API_TOKEN": "your_static_api_token",
        "BASE_URL": "https://www.tatilsepeti.com"
      }
    }
  }
}

Manual Run

node mcp.js

Available Tools

1. search_destination

Search for travel destinations (regions/locations).

Parameters:

• query (string): Destination name (e.g., "antalya", "bodrum", "istanbul")

Returns:

[
  { "regionId": 34, "subRegionId": 0, "type": 0, "title": "Antalya" }
]

2. list_hotels

List hotels for a specific region — sıralama ve filtre destekli.

Parameters:

• regionId (number): Region ID from search_destination
• subRegionId (number, optional): Sub-region ID (default: 0)
• type (number, optional): Tip (default: 0)
• checkinDate / checkoutDate (string): YYYY-MM-DD
• adultCount / childCount / childAges: misafir bilgisi
• pageNumber / pageSize: sayfalama (default: 1 / 20)
• sortBy (optional): popular (default) | priceAsc | priceDesc | score
• minPrice / maxPrice (number, optional): fiyat aralığı filtresi (0 = filtresiz)
• isAvailableHotels (boolean, optional): sadece müsait otelleri göster
• oneChildFree / twoChildFree (boolean, optional): çocuk ücretsiz kampanyası
• hasMinistryOfHealthCertificate (boolean, optional): Sağlık Bakanlığı sertifikalı tesisler

Returns:

{
  "totalCount": 155,
  "currentPage": 1,
  "pageSize": 20,
  "showingCount": 20,
  "hotels": [
    {
      "hotelId": 12345,
      "name": "Hotel Name",
      "star": 5,
      "score": 8.9,
      "scoreText": "Harika",
      "reviewCount": 150,
      "location": "Kemer, Antalya",
      "price": 10500,
      "discountRate": 30,
      "accommodation": "Her Şey Dahil",
      "campaignName": "Son Dakika %30 İndirim",
      "properties": ["Aquapark", "Spa", "Denize Sıfır"],
      "isFreeCancellation": true,
      "image": "https://cdn.tatilsepeti.com/...",
      "link": "https://www.tatilsepeti.com/hotel-url"
    }
  ]
}

hotelId, aşağıdaki hotel_detail / hotel_rooms / hotel_reviews tool'larına geçirilmek üzere dönülür.

3. hotel_detail

Bir otelin detay bilgilerini (açıklama, olanaklar, konum) getirir.

Parameters:

• hotelId (number): list_hotels'ten alınan otel ID
• checkinDate / checkoutDate (string): YYYY-MM-DD
• adultCount / childCount / childAges: misafir bilgisi

Returns: API'nin resultObject'i olduğu gibi döner (otel açıklaması, olanaklar, konum, genel puan vb. — alanlar API sürümüne göre değişebilir).

4. hotel_rooms

Bir otelin müsait oda tiplerini ve fiyatlarını getirir.

Parameters: hotel_detail ile aynı (hotelId, checkinDate, checkoutDate, misafir bilgisi)

Returns: Oda tipi listesi, her biri fiyat/pansiyon/iptal koşulu bilgisiyle (resultObject olduğu gibi döner).

5. hotel_reviews

Bir otelin misafir yorumlarını getirir.

Parameters:

• hotelId (number)
• source (optional): all (default) | tatilsepeti | tripadvisor
• page / pageSize: sayfalama (default: 1 / 10)

Returns: Yorum listesi ve puan özeti (resultObject olduğu gibi döner).

Example Workflow

User: "Antalya'da otel bul"
→ search_destination(query: "antalya")
→ Returns: regionId: 34

→ list_hotels(regionId: 34, checkinDate: "2025-12-24", checkoutDate: "2025-12-27", sortBy: "priceAsc")
→ Returns: 20 otel, her biri hotelId ile

→ hotel_detail(hotelId: 12345, checkinDate: "2025-12-24", checkoutDate: "2025-12-27")
→ Returns: otel açıklaması, olanaklar, konum

→ hotel_rooms(hotelId: 12345, checkinDate: "2025-12-24", checkoutDate: "2025-12-27")
→ Returns: oda tipleri ve fiyatları

→ hotel_reviews(hotelId: 12345)
→ Returns: misafir yorumları

Auth

Sabit bir API_TOKEN, her isteğe Authorization: Bearer <API_TOKEN> olarak eklenir — yenileme/refresh mantığı yoktur. Token expire olursa (401) server hatayı olduğu gibi döner; yeni bir token alıp .env'i güncellemek gerekir.

Architecture

┌─────────────────┐
│  Claude/Client  │
└────────┬────────┘
         │ MCP Protocol
         │
┌────────▼────────┐
│   MCP Server    │
│   (mcp.js)      │
└────────┬────────┘
         │
         │ lib/api.js — static Bearer token
         │ /api/v1 (search, detail, rooms) + /api/v2 (list, reviews)
         │
┌────────▼────────┐
│ Tatilsepeti API │
└─────────────────┘

Development

# Install dependencies
npm install

# Run MCP server
npm start

License

MIT