booking-mcp

# Booking.com MCP Server

<!-- mcp-name: com.hasdata/booking -->

A hosted Model Context Protocol (MCP) server that gives Claude, Cursor, Windsurf and any other MCP client two read-only Booking.com tools. Search stays by destination and dates with rich filters, and read a single property in full, all as structured JSON, with no Booking.com account and nothing to host.

It reads public property pages on Booking.com that a signed-out visitor can see.

```
https://mcp.hasdata.com/api/mcp?apis=booking
```

[![Glama score](https://glama.ai/mcp/servers/HasData/booking-mcp/badges/score.svg)](https://glama.ai/mcp/servers/HasData/booking-mcp)
[![tool contract](https://github.com/HasData/booking-mcp/actions/workflows/contract.yml/badge.svg)](https://github.com/HasData/booking-mcp/actions/workflows/contract.yml)
[![MCP](https://img.shields.io/badge/MCP-remote%20%7C%20streamable%20HTTP-6366f1?style=flat-square)](https://modelcontextprotocol.io)
[![Tools](https://img.shields.io/badge/tools-2-10b981?style=flat-square)](#tools)
[![License](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)

## Contents

- [What you need](#what-you-need)
- [Quick start](#quick-start)
- [Example prompts](#example-prompts)
- [Tools](#tools)
- [Errors and failure paths](#errors-and-failure-paths)
- [Pricing, free tier and limits](#pricing-free-tier-and-limits)
- [Tool selection](#tool-selection)
- [How it compares](#how-it-compares)
- [FAQ](#faq)
- [HasData links](#hasdata-links)
- [Development](#development)
- [Contributing](#contributing)
- [License](#license)

## What you need

An MCP client and a HasData API key from the [dashboard](https://app.hasdata.com/sign-up?utm_source=github&utm_medium=syndication&utm_campaign=booking-mcp), free to create with no card, and the trial covers 100 calls at the 10-credit rate. This is a remote server, so the simplest path is a URL and an `x-api-key` header, with no container to run and no Booking.com account anywhere in the flow. A client that only speaks stdio reaches it through a thin launcher, published as `@hasdata/booking-mcp` on npm and `hasdata-booking-mcp` on PyPI, shown below.

## Quick start

The server URL is the same for every client. We run it hands-on in Claude Code and Claude Desktop. The other blocks follow each client's own documented format for a remote server.

| Field | Value |
| :--- | :--- |
| URL | `https://mcp.hasdata.com/api/mcp?apis=booking` |
| Transport | HTTP, streamable |
| Auth header | `x-api-key: HASDATA_API_KEY` |

Clients with OAuth support can add the same URL as a connector and sign in without putting a key in a config file.

<details>
<summary><b>Claude Code</b></summary>

```bash
claude mcp add --transport http booking "https://mcp.hasdata.com/api/mcp?apis=booking" \
  --header "x-api-key: HASDATA_API_KEY"
```

</details>

<details>
<summary><b>Claude Desktop</b></summary>

Settings, then Connectors, then Add custom connector, then paste `https://mcp.hasdata.com/api/mcp?apis=booking` and sign in.

For the config-file route, Claude Desktop loads only local (stdio) servers, so it reaches a remote server through a stdio launcher. The `@hasdata/booking-mcp` package is that launcher, and it reads the key from the environment. Add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "booking": {
      "command": "npx",
      "args": ["-y", "@hasdata/booking-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

For Python instead of Node, swap the launcher for the PyPI package, which `uvx` runs without a manual install:

```json
{
  "mcpServers": {
    "booking": {
      "command": "uvx",
      "args": ["hasdata-booking-mcp"],
      "env": { "HASDATA_API_KEY": "YOUR_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Cursor</b></summary>

`~/.cursor/mcp.json` for every project, or `.cursor/mcp.json` for one:

```json
{
  "mcpServers": {
    "booking": {
      "url": "https://mcp.hasdata.com/api/mcp?apis=booking",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>Windsurf</b></summary>

`~/.codeium/windsurf/mcp_config.json`. Windsurf calls the field `serverUrl`, not `url`:

```json
{
  "mcpServers": {
    "booking": {
      "serverUrl": "https://mcp.hasdata.com/api/mcp?apis=booking",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

<details>
<summary><b>VS Code</b></summary>

`.vscode/mcp.json` in the workspace:

```json
{
  "servers": {
    "booking": {
      "type": "http",
      "url": "https://mcp.hasdata.com/api/mcp?apis=booking",
      "headers": { "x-api-key": "HASDATA_API_KEY" }
    }
  }
}
```

</details>

## Example prompts

Prompts, not code. Paste one in and the agent picks the tool itself. Each is annotated with the calls it takes, because every successful call costs 10 credits.

> Search Booking.com for hotels in Paris from September 15 to 18 for two adults, and give me the ten best-reviewed under $700 for the stay.

*One call, 10 credits. Price, review score and location come back on the search result.*

> Take the top result and pull its full detail: facilities, house rules, the room options, and the category ratings.

*One call, 10 credits. Those live on the property page, which the details tool reads by URL and dates.*

> Find four-star hotels in Paris with free cancellation near the center, and list price and review score.

*One call, 10 credits. Star rating, cancellation policy and distance are filters on the one request.*

> Compare the cheapest stay in Paris against Rome for the same dates.

*Two calls, 20 credits, one search per city.*

The property tool needs the same dates and guest counts as the search, because availability and price depend on the window. A search to shortlist plus a detail call on three properties is one search and three property calls.

## Tools

Two tools, read-only. Samples below are trimmed from real calls, and prices move constantly. Read them as shapes. Each tool name links to its endpoint reference, which carries the full field list.

The samples are the payload, not the whole response. A `tools/call` result carries one text block, and that text is itself JSON holding `url`, `status`, `text` and `json`, with the scraped data under `json`. From a raw JSON-RPC response the path is `result.content[0].text`, parsed, then `.json`. A chat client unwraps that for you and code talking to the endpoint directly does not.

### Get Booking.com search results

[`hasdata_booking_search_getBookingSearchResults`](https://docs.hasdata.com/apis/booking/search?utm_source=github&utm_medium=syndication&utm_campaign=booking-mcp)

A page of stays by destination and dates.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `keyword` | string | yes | Destination, such as `Paris` or a specific property name |
| `checkInDate` / `checkOutDate` | string | yes | `YYYY-MM-DD`, check-in in the future and before check-out |
| `rooms` / `adults` / `children` | number | yes | Guest composition. Pass `children: 0` when there are none |
| `childrenAges` | string | | Comma-separated ages, required when `children > 0` |
| `sort` | string | | `priceLowestFirst`, `ratingHighToLow`, `bestReviewedAndLowestPrice`, `distanceFromDowntown` and more |
| `propertyType__` / `rating__` / `reviewScore__` | array | | Property type, star rating, and guest-score buckets |
| `facilities__` / `roomFacilities__` / `reservationPolicy__` | array | | Facility, in-room and cancellation filters |
| `price_min_` / `price_max_` | number | | Total-stay price band |
| `page` | number | | About 25 results per page, `2` for the next page |

The reference documents the full filter set, including distance, meals, accessibility, bed preference and travel group.

Returns `searchInformation`, a `results` array, and `pagination` with `page`, `totalResults` and `totalPages`. Each result carries `hotelId`, `title`, `url`, the offered `room` and `bedTypes`, a `location` object, a `policies` object, a `price` object, the star `rating`, a `reviews` object with `score`, `count` and a text label, and a `photo`.

> The discount field in `price` is spelled `dicsount` (`dicsountRaw` and `dicsountParsed`), which mirrors the upstream key. Read that spelling, not `discount`. Also note `rating` is the official star rating while `reviews.score` is the guest score out of 10, two different numbers.

```json
{
  "hotelId": 50724,
  "title": "Hôtel du Jardin des Plantes",
  "url": "https://www.booking.com/hotel/fr/timjardindesplantes.html",
  "room": "Comfort Double Room",
  "location": { "city": "Paris", "address": "5 rue Linné", "mainDistance": "0.9 miles from downtown", "centrallyLocated": true },
  "policies": { "freeCancellation": true, "noPrepayment": true },
  "price": { "pricePerStayParsed": 451.36, "priceBeforeDiscountParsed": 885.03, "dicsountParsed": 433.66, "currency": "USD" },
  "rating": 3,
  "reviews": { "score": 7.5, "count": 1721, "text": "Good" }
}
```

### Get Booking.com property details

[`hasdata_booking_place_getBookingPlaceDetails`](https://docs.hasdata.com/apis/booking/place?utm_source=github&utm_medium=syndication&utm_campaign=booking-mcp)

One property in full, by its URL and the stay window.

| Parameter | Type | Required | Notes |
| :--- | :--- | :--- | :--- |
| `url` | string | yes | A Booking.com property URL, the `url` field from a search result |
| `checkInDate` / `checkOutDate` | string | yes | `YYYY-MM-DD`, the window to price and check availability for |
| `rooms` / `adults` / `children` | number | yes | Guest composition, same meaning as the search tool |
| `childrenAges` | string | | Comma-separated ages, required when `children > 0` |

Returns the page as sections rather than one flat object: `overview` (`id`, `title`, `propertyType`, a structured `address`, a `description`, `highlights`, `mostPopularFacilities` and `photos`), `bookingDetails` (the window and currency the prices reflect), a `rooms` array of th