wuyq0808/skyscanner-mcp

Hotel Search MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with hotel search capabilities using stdio transport. Deployed on Google Cloud Run.

Features

• 🏨 Hotel Search - Search for hotels by destination, dates, and filters
• 📋 Hotel Details - Get comprehensive hotel information including amenities
• 🌍 Destinations - List available destinations for hotel search
• 🔍 Filtering - Filter by price range, rating, amenities, and more
• 💾 Caching - Built-in result caching for improved performance
• 🏷️ Type Safety - Full TypeScript implementation with proper type definitions

Prerequisites

• Node.js 18+
• TypeScript
• Hotel search API key (configurable)

Quick Start

Installation

git clone <repository-url>
cd skyscanner-mcp
npm install

Build

npm run build

Configuration

Set the required environment variables:

export HOTEL_SEARCH_API_KEY="your-hotel-api-key-here"
export HOTEL_SEARCH_BASE_URL="https://api.hotelexample.com/v1"  # Optional

Usage

As Stdio MCP Server

Run the hotel search MCP server with stdio transport:

npm run start:mcp
# or manually:
HOTEL_SEARCH_API_KEY="your-key" node dist/mcp-tools/bin/hotel-search-mcp-server

As HTTP MCP Server

Run the hotel search MCP server with streamable HTTP transport:

npm run dev:http
# or for production:
HOTEL_SEARCH_API_KEY="your-key" npm start

The HTTP server provides:

• Homepage: http://localhost:3000/ - Server info and status
• MCP Endpoint: http://localhost:3000/api/hotel-search-mcp - Streamable HTTP MCP endpoint
• Health Check: http://localhost:3000/health - Service health status

With Claude Desktop (Stdio)

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "hotel-search": {
      "command": "node",
      "args": ["/path/to/skyscanner-mcp/dist/mcp-tools/bin/hotel-search-mcp-server"],
      "env": {
        "HOTEL_SEARCH_API_KEY": "your-api-key-here"
      }
    }
  }
}

With OpenAI/Claude API (HTTP)

Use the HTTP endpoint for integration with AI platforms that support MCP over HTTP:

# Start the HTTP server
HOTEL_SEARCH_API_KEY="your-key" npm start

# MCP endpoint available at:
# http://localhost:3000/api/hotel-search-mcp

MCP Tools

hotel_search__search_hotels

Search for hotels based on criteria.

Parameters:

• destination (optional): Destination city (e.g., "London, UK")
• check_in (optional): Check-in date (YYYY-MM-DD format)
• check_out (optional): Check-out date (YYYY-MM-DD format)
• guests (optional): Number of guests (default: 2)
• rooms (optional): Number of rooms (default: 1)
• price_min (optional): Minimum price per night
• price_max (optional): Maximum price per night
• min_rating (optional): Minimum hotel rating (1-5 stars)
• amenities (optional): Comma-separated amenities (e.g., "WiFi,Pool,Gym")

Returns: CSV format with hotel details including ID, name, location, price, rating, and amenities.

hotel_search__get_hotel_details

Get detailed information about a specific hotel.

Parameters:

• hotel_id (required): Unique hotel identifier from search results

Returns: Detailed hotel information including full description, amenities list, and images.

hotel_search__get_available_destinations

Get a list of popular destinations available for hotel search.

Parameters: None

Returns: List of available destinations.

hotel_search__health_check

Check if the hotel search API is available and responding.

Parameters: None

Returns: Health status of the hotel search service.

Architecture

The MCP server follows the official MCP SDK patterns:

src/mcp-tools/hotel-search/
├── hotel-search-client.ts          # API client with caching
├── hotel-search-tools.ts           # LangChain tool definitions  
├── hotel-search-mcp-server-stdio.ts # MCP stdio server
└── bin/hotel-search-mcp-server      # Executable entry point

Key Components

• HotelSearchAPIClient: Handles API communication and caching
• HotelSearchTools: LangChain tool wrappers with Zod schemas
• HotelSearchMCPStdioServer: MCP server with stdio transport
• Shared utilities: Common MCP utilities for tool registration

Development

Scripts

npm run build          # Build TypeScript
npm run dev            # Development with watch mode  
npm run typecheck      # Type checking only
npm run lint           # ESLint code analysis
npm run lint:fix       # Fix linting issues
npm run format         # Format code with Prettier

Testing

# Test the MCP server directly
HOTEL_SEARCH_API_KEY="test-key" node dist/mcp-tools/bin/hotel-search-mcp-server

# Test with MCP client
npm run test:script -- test-hotel-search.ts

API Integration

Currently uses stub/mock data. To integrate with a real hotel search API:

1. Update HotelSearchAPIClient in hotel-search-client.ts
2. Implement actual HTTP calls to your hotel API
3. Update error handling and response parsing
4. Configure proper authentication headers

Example API Integration

async searchHotels(filters: SearchFilters): Promise<HotelSearchResult[]> {
  const response = await fetch(`${this.baseUrl}/search`, {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${this.apiKey}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(filters)
  });
  
  if (!response.ok) {
    throw new Error(`Hotel search failed: ${response.statusText}`);
  }
  
  return await response.json();
}

Dependencies

• @modelcontextprotocol/sdk: ^1.15.1 - Official MCP SDK
• @langchain/core: 0.3.66 - LangChain tool framework
• zod: 3.25.67 - Runtime type validation
• csv-stringify: ^6.6.0 - CSV output formatting
• date-fns: ^4.1.0 - Date manipulation utilities

Environment Variables

License

MIT License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run npm run lint and npm run typecheck
6. Submit a pull request

Support

For issues and questions:

1. Check the existing issues
2. Create a new issue with detailed description
3. Include environment details and error messages