# Hostelworld MCP tools

> Every Hostelworld MCP tool on the Cotlet server: tool names, input schemas, a tools/call example and an example result for each tool.

Source: https://cotlet.dev/docs/mcp/hostelworld

Docs sections: [Get started](https://cotlet.dev/docs.md) · [REST API](https://cotlet.dev/docs/api.md) · [MCP](https://cotlet.dev/docs/mcp.md) · [SDKs & CLI](https://cotlet.dev/docs/sdks.md) · [Integrations](https://cotlet.dev/docs/integrations.md)

15 tools for Hostelworld on the Cotlet MCP server. Your agent picks them from tools/list.

- MCP server: `https://cotlet.dev/mcp/v1`
- Connects with: Your own Hostelworld Inbox (property) account; PayNow tools need a Manager user
- Integration page: https://cotlet.dev/integrations/hostelworld-api-mcp-server

## Endpoints

| Endpoint | Access | Description |
|---|---|---|
| `hostelworld_list_new_bookings` | read | Bookings in the New Bookings tab that you have not acknowledged yet. |
| `hostelworld_search_bookings` | read | Advanced Search by arrival or booked date, or by reference, guest name or email. |
| `hostelworld_get_booking` | read | Booking details: guest, dates, rooms or beds, rate type, deposit paid, balance due and status. No card data. |
| `hostelworld_list_reviews` | read | Reviews from Reports > Customer Ratings, with ratings, text, booking reference and whether you replied. |
| `hostelworld_list_chats` | read | Guest chats in the Inbox, newest first, with booking reference and unread flag. |
| `hostelworld_get_chat` | read | All messages in one guest chat, and whether it is still open or read-only after checkout. |
| `hostelworld_list_payouts` | read | PayNow payouts from Property Setup > Finance > Pay Now: date, status, amount, masked bank account, plus balance and next payout date. Manager users only. |
| `hostelworld_get_payout` | read | One payout: timeline, Payout Trace ID, charges, refunds, adjustments, fees, net amount and every payment it includes. |
| `hostelworld_export_guest_payments` | read | Guest Payments export as a CSV download link, with booking IDs for reconciliation. Manager users only. |
| `hostelworld_acknowledge_booking` | write | Click "I have read this booking" so the booking leaves the New Bookings tab and Hostelworld knows you picked it up. |
| `hostelworld_reply_to_review` | write | Public reply under a review. Hostelworld checks it before publishing and it cannot be edited after. |
| `hostelworld_query_review` | write | Send a review to a Hostelworld moderator when you believe it breaks the review guidelines. |
| `hostelworld_send_chat_message` | write | Reply to a guest in Property Chat, or start a chat from a booking when the Chat option is available. |
| `hostelworld_report_payment_issue` | write | Report Payment Issue on a booking: the guest gets an email asking them to pay. |
| `hostelworld_mark_no_show` | write | Cancel a booking as a no-show and email the guest. Available from the check-in date, not for Pay Now. |

## List new bookings

MCP tool: `hostelworld_list_new_bookings`

Access: read.

Returns the bookings waiting in the New Bookings tab, with the booking reference, guest name, arrival date and booked date. A booking leaves the list once you acknowledge it. With a channel manager the list is usually empty, because bookings are acknowledged there. Pass booking_ref to get_booking for full details.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_new_bookings",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "bookings": [
      {
        "booking_ref": "412-305871264",
        "guest": "Jan Kowalski",
        "arrival": "2026-10-18",
        "nights": 2,
        "booked_at": "2026-10-10T21:14:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Search bookings

MCP tool: `hostelworld_search_bookings`

Access: read.

Searches acknowledged and new bookings the way the Inbox search bar and Advanced Search do. Use a date range with date_type, or query for a booking reference, guest name or email. Results show reference, guest, arrival date and status. Pass booking_ref to get_booking for the details.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `date_type` | enum | no | arrival or booked. Default: arrival. |
| `from` | date | no | Start of the date range. |
| `to` | date | no | End of the date range. |
| `query` | string | no | Booking reference, guest name or email instead of dates. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_search_bookings",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "bookings": [
      {
        "booking_ref": "412-305871264",
        "guest": "Jan Kowalski",
        "arrival": "2026-10-10",
        "nights": 1,
        "status": "confirmed"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get booking

MCP tool: `hostelworld_get_booking`

Access: read.

Returns one booking as the booking page shows it: guest, arrival date, nights, room type and number of people, rate type, deposit paid, balance due and status. Card information is never returned. Use it before mark_no_show or report_payment_issue to check the status and the rate type.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_ref` | string | yes | Hostelworld booking reference from search_bookings or list_new_bookings. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_get_booking",
    "arguments": {
      "booking_ref": "booking ref"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "confirmed",
    "guest": "Jan Kowalski",
    "arrival": "2026-10-10",
    "nights": 1,
    "room": "6-bed mixed dorm",
    "guests": 1,
    "rate_type": "flexible",
    "currency": "EUR",
    "total": 24,
    "deposit_paid": 2.4,
    "balance_due": 21.6
  },
  "isError": false
}
```

## List reviews

MCP tool: `hostelworld_list_reviews`

Access: read.

Returns the reviews that came in during the date range, the same list as Reports > Customer Ratings. Hostelworld allows a range of up to one year at a time. Set unanswered_only to skip reviews you replied to. Pass booking_ref to reply_to_review or query_review.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | yes | Start date. The range can be up to one year. |
| `to` | date | yes | End date. |
| `unanswered_only` | boolean | no | Skip reviews you already replied to. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_reviews",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "reviews": [
      {
        "booking_ref": "412-305871264",
        "rating": 7.1,
        "text": "Great location, but no hot water in the morning.",
        "language": "en",
        "replied": false,
        "reviewed_at": "2026-10-05T09:30:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## List guest chats

MCP tool: `hostelworld_list_chats`

Access: read.

Lists Property Chat conversations, newest first, with the guest name, booking reference and whether there are unread messages. Property Chat must be switched on in Inbox first. Pass chat_id to get_chat.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `unread_only` | boolean | no | Only chats with unread guest messages. |
| `limit` | integer | no | 1 to 100. Default: 50. |
| `cursor` | string | no | Next page cursor from the previous call. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_chats",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "chats": [
      {
        "chat_id": "ch_77a2",
        "booking_ref": "412-305871264",
        "guest": "Jan Kowalski",
        "unread": true,
        "last_message": "What time can I check in?",
        "updated_at": "2026-10-09T15:02:00Z"
      }
    ],
    "next_cursor": null
  },
  "isError": false
}
```

## Get chat

MCP tool: `hostelworld_get_chat`

Access: read.

Returns the messages of one chat, oldest first, as text. Chats are open from the confirmed booking until the guest checks out and read-only after that. Images and files are not part of Property Chat.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `chat_id` | string | yes | Chat ID from list_chats. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_get_chat",
    "arguments": {
      "chat_id": "chat_8c41d2"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "chat_id": "ch_77a2",
    "booking_ref": "412-305871264",
    "open": true,
    "messages": [
      {
        "from": "guest",
        "body": "What time can I check in?",
        "sent_at": "2026-10-09T15:02:00Z"
      }
    ]
  },
  "isError": false
}
```

## List payouts

MCP tool: `hostelworld_list_payouts`

Access: read.

Returns the Payouts tab: total balance, estimated next payout date and each payout with date, status, masked destination and amount. Status is initiated, in transit or completed. Only Manager user accounts in Inbox can view PayNow. Pass payout_id to get_payout.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `status` | enum | no | all, initiated, in_transit or completed. Default: all. |
| `from` | date | no | Payouts on or after this date. |
| `to` | date | no | Payouts on or before this date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_list_payouts",
    "arguments": {}
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "balance": {
      "amount": 464.4,
      "currency": "EUR"
    },
    "next_payout_date": "2026-10-14",
    "payouts": [
      {
        "payout_id": "po_2026_10_07",
        "date": "2026-10-07",
        "status": "completed",
        "destination": "Bank account ****4821",
        "amount": 464.4,
        "currency": "EUR"
      }
    ]
  },
  "isError": false
}
```

## Get payout

MCP tool: `hostelworld_get_payout`

Access: read.

Returns the payout side panel: status timeline, destination, Payout Trace ID, a summary of charges, refunds, adjustments and fees with gross and net, and every payment in the payout. Give the trace ID to your bank if a completed payout has not arrived after 5 business days. Manager users only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `payout_id` | string | yes | Payout ID from list_payouts. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_get_payout",
    "arguments": {
      "payout_id": "po_2026_10_07"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "payout_id": "po_2026_10_07",
    "status": "completed",
    "trace_id": "tr_9F21K0Q4",
    "summary": {
      "charges": 520,
      "refunds": 40,
      "adjustments": 0,
      "fees": 15.6,
      "net": 464.4,
      "currency": "EUR"
    },
    "transactions": [
      {
        "booking_ref": "412-305871264",
        "amount": 200,
        "status": "succeeded"
      },
      {
        "booking_ref": "412-305871377",
        "amount": 180,
        "status": "succeeded"
      },
      {
        "booking_ref": "412-305871402",
        "amount": 140,
        "status": "refunded",
        "refunded": 40
      }
    ]
  },
  "isError": false
}
```

## Export guest payments

MCP tool: `hostelworld_export_guest_payments`

Access: read.

Generates the Guest Payments CSV for a date range and returns a download link. The file includes the booking ID, which matches your Hostelworld booking reference. Manager users only.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `from` | date | yes | Start date. |
| `to` | date | yes | End date. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_export_guest_payments",
    "arguments": {
      "from": "2026-10-01",
      "to": "2026-10-01"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "url": "https://files.cotlet.example/exports/guest-payments-2026-09-30_2026-10-06.csv",
    "rows": 3,
    "from": "2026-09-30",
    "to": "2026-10-06"
  },
  "isError": false
}
```

## Acknowledge booking

MCP tool: `hostelworld_acknowledge_booking`

Access: write. Confirm: waits for the user's OK before it runs.

Marks one new booking as read. It leaves the New Bookings tab, stays in Inbox and stays searchable. Hostelworld asks you to do this for every booking. It cannot be undone with a tool. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_ref` | string | yes | Hostelworld booking reference from search_bookings or list_new_bookings. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_acknowledge_booking",
    "arguments": {
      "booking_ref": "booking ref"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "acknowledged"
  },
  "isError": false
}
```

## Reply to review

MCP tool: `hostelworld_reply_to_review`

Access: write. Confirm: waits for the user's OK before it runs.

Submits an owner's reply to one review. Write it in the language of the review or in English, and leave out the guest's name. Hostelworld checks the reply against its guidelines before it is published, and you cannot edit it after you submit it. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_ref` | string | yes | Hostelworld booking reference from search_bookings or list_new_bookings. |
| `body` | string | yes | Reply in the review's language or English. Do not use the guest's name. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_reply_to_review",
    "arguments": {
      "booking_ref": "412-305871264",
      "body": "Thanks for staying with us! We have fixed the hot water in dorm 3 since your visit. Hope to see you again."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "pending_moderation",
    "submitted_at": "2026-10-11T14:22:05+02:00",
    "editable": false
  },
  "isError": false
}
```

## Query review

MCP tool: `hostelworld_query_review`

Access: write. Confirm: waits for the user's OK before it runs.

Sends your comments about one review to a Hostelworld moderator, who reviews it and replies to you. Hostelworld does not remove a genuine unfavorable review without sufficient evidence of a breach of its Review Guidelines, so include the evidence. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_ref` | string | yes | Hostelworld booking reference from search_bookings or list_new_bookings. |
| `reason` | string | yes | Why the review breaks the guidelines, with evidence. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_query_review",
    "arguments": {
      "booking_ref": "booking ref",
      "reason": "reason"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "sent_to_moderator"
  },
  "isError": false
}
```

## Send chat message

MCP tool: `hostelworld_send_chat_message`

Access: write. Confirm: waits for the user's OK before it runs.

Sends a text message to a guest in Property Chat. Use chat_id to reply, or booking_ref to message from a booking when Hostelworld shows the Chat option for it. Chat supports text only and is read-only after the guest checks out. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `chat_id` | string | no | Chat ID from list_chats. Use this or booking_ref. |
| `booking_ref` | string | no | Start a new chat from this booking. |
| `body` | string | yes | Message text. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_send_chat_message",
    "arguments": {
      "chat_id": "ch_77a2",
      "body": "Hi! Check-in opens at 14:00. You can leave your bag in our luggage room from 08:00. After 22:00, ring the bell at the side door."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "chat_id": "ch_77a2",
    "status": "sent",
    "sent_at": "2026-10-09T15:10:00+02:00"
  },
  "isError": false
}
```

## Report payment issue

MCP tool: `hostelworld_report_payment_issue`

Access: write. Confirm: waits for the user's OK before it runs.

Triggers Hostelworld's automatic payment request email to the guest. Use it only when the payment deadline in your policy has expired and your terms were visible at booking. If the guest does not pay within 24 hours, you can ask Hostelworld support to cancel the booking. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_ref` | string | yes | Hostelworld booking reference from search_bookings or list_new_bookings. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_report_payment_issue",
    "arguments": {
      "booking_ref": "booking ref"
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "payment_request_sent"
  },
  "isError": false
}
```

## Mark as no-show

MCP tool: `hostelworld_mark_no_show`

Access: write. Confirm: waits for the user's OK before it runs.

Marks the booking as a no-show, which cancels it and emails the guest. It works from the check-in date until 23:59 on that date for a one-night booking, or 48 hours after check-in for a longer stay. It does not apply to Pay Now rates or to a group where only one guest is missing. Your comment goes to Hostelworld support, not to the guest. By default you confirm each call; you can switch that off for this tool.

### Parameters

| Name | Type | Required | Description |
|---|---|---|---|
| `booking_ref` | string | yes | Hostelworld booking reference from search_bookings or list_new_bookings. |
| `comment` | string | no | Note for Hostelworld support, not shown to the guest. |

### tools/call

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hostelworld_mark_no_show",
    "arguments": {
      "booking_ref": "412-306110482",
      "comment": "Guest did not arrive by 22:30 and sent no message."
    }
  }
}
```

### Example response

```json
{
  "content": [
    {
      "type": "text",
      "text": "{ ... same JSON as structuredContent ... }"
    }
  ],
  "structuredContent": {
    "booking_ref": "412-305871264",
    "status": "cancelled_no_show"
  },
  "isError": false
}
```